diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..a377943b --- /dev/null +++ b/.gitattributes @@ -0,0 +1,2 @@ +*.cs -text +*.vb -text \ No newline at end of file diff --git a/.github/workflows/auto-publish.yml b/.github/workflows/auto-publish.yml new file mode 100644 index 00000000..aae337b6 --- /dev/null +++ b/.github/workflows/auto-publish.yml @@ -0,0 +1,38 @@ +name: auto-publish +run-name: Automatically publish documentation +on: + schedule: + - cron: '45 23 * * WED' +jobs: + auto-publish: + runs-on: ubuntu-latest + permissions: + contents: write + defaults: + run: + shell: bash + working-directory: ./ + steps: + - name: Check out repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + - name: Check out main + run: | + echo "Checking out main branch" + git config user.name github-actions + git config user.email github-actions@github.com + git checkout main + - name: Check out live + run: | + echo "Checking out live branch" + git checkout live + - name: Merge from main into live + run: | + echo "Merging from main to live" + git merge main + - name: Push changes + run: | + echo "Pushing changes to live branch" + git push origin live + diff --git a/.gitignore b/.gitignore index 4f4f50e5..f14cbd54 100644 --- a/.gitignore +++ b/.gitignore @@ -287,4 +287,6 @@ __pycache__/ *.odx.cs *.xsd.cs -docs/open-xml-docs/ \ No newline at end of file +docs/open-xml-docs/ +samples/**/Properties/**/* +samples/**/My\ Project/**/* diff --git a/.openpublishing.publish.config.json b/.openpublishing.publish.config.json index 5e32ffad..e83d1548 100644 --- a/.openpublishing.publish.config.json +++ b/.openpublishing.publish.config.json @@ -6,13 +6,42 @@ "build_output_subfolder": "open-xml-docs", "locale": "en-us", "monikers": [], - "moniker_ranges": [], + "moniker_ranges": [ + "openxml-2.7.1", + "openxml-2.7.2", + "openxml-2.8.0", + "openxml-2.8.1", + "openxml-2.9.0", + "openxml-2.9.1", + "openxml-2.10.0", + "openxml-2.10.1", + "openxml-2.11.0", + "openxml-2.11.1", + "openxml-2.11.2", + "openxml-2.11.3", + "openxml-2.12.0", + "openxml-2.12.1", + "openxml-2.12.2", + "openxml-2.12.3", + "openxml-2.13.0", + "openxml-2.13.1", + "openxml-2.14.0", + "openxml-2.15.0", + "openxml-2.16.0", + "openxml-2.17.1", + "openxml-2.18.0", + "openxml-2.19.0", + "openxml-2.20.0", + "openxml-3.0.0", + "openxml-3.0.1" + ], "open_to_public_contributors": true, "customized_tasks": { "docset_prebuild": [ "_dependentPackages/CommonPlugins/tools/JoinTOC.ps1" ] }, + "xref_query_tags": [ "/dotnet" ], "type_mapping": { "Conceptual": "Content", "ManagedReference": "Content", diff --git a/LICENSE b/LICENSE index 4b1ad51b..21071075 100644 --- a/LICENSE +++ b/LICENSE @@ -1,21 +1,21 @@ - MIT License - - Copyright (c) Microsoft Corporation. All rights reserved. - - Permission is hereby granted, free of charge, to any person obtaining a copy - of this software and associated documentation files (the "Software"), to deal - in the Software without restriction, including without limitation the rights - to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - copies of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be included in all - copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - SOFTWARE + MIT License + + Copyright (c) Microsoft Corporation. All rights reserved. + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to deal + in the Software without restriction, including without limitation the rights + to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included in all + copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE diff --git a/docs/about-the-open-xml-sdk.md b/docs/about-the-open-xml-sdk.md index 6a12d435..6ab0ad18 100644 --- a/docs/about-the-open-xml-sdk.md +++ b/docs/about-the-open-xml-sdk.md @@ -62,11 +62,11 @@ The SDK supports the following common tasks/scenarios: ## Open XML SDK for Office -The Open XML SDK provides the namespaces and members to support the Microsoft Office 2013. The Open XML SDK can also read ISO/IEC 29500 Strict Format files. The Strict format is a subset of the Transitional format that does not include legacy features - this makes it theoretically easier for a new implementer to support since it has a smaller technical footprint. +The Open XML SDK provides the namespaces and members to support the Microsoft Office. The Open XML SDK can also read ISO/IEC 29500 Strict Format files. The Strict format is a subset of the Transitional format that does not include legacy features - this makes it theoretically easier for a new implementer to support since it has a smaller technical footprint. The SDK supports the following common tasks/scenarios: -- **Support of Office 2013 Preview file format** In addition to the Open XML SDK for Microsoft Office classes, Open XML SDK provides new classes that enable you to write and build applications to manipulate Open XML file extensions of the new Office 2013 features. +- **Support of Office Preview file format** In addition to the Open XML SDK for Microsoft Office classes, Open XML SDK provides new classes that enable you to write and build applications to manipulate Open XML file extensions of the new Office features. - **Reads ISO Strict Document File** Open XML SDK can read ISO/IEC 29500 Strict Format files. When the Open XML SDK API opens a Strict Format file, each Open XML part in the file is loaded to an **OpenXmlPart** class of the Open XML SDK by mapping `https://purl.oclc.org/ooxml/` namespaces to the corresponding `https://schemas.openxmlformats.org/` namespaces. - **Fixes to the Open XML SDK for Microsoft Office** Open XML SDK includes fixes to known issues in the Open XML SDK for Microsoft Office. These include lost whitespaces in PowerPoint presentations and an issue with the Custom UI in Word documents where a specified argument was reported as being out of the range of valid values. diff --git a/docs/docfx.json b/docs/docfx.json index fe6c0e66..14da17ef 100644 --- a/docs/docfx.json +++ b/docs/docfx.json @@ -32,6 +32,8 @@ "overwrite": [], "externalReference": [], "globalMetadata": { + "ms.subservice": "open-xml", + "ms.service": "office", "breadcrumb_path": "/office/open-xml/breadcrumb/toc.json", "extendBreadcrumb": true, "uhfHeaderId": "MSDocsHeader-Dev_Office", @@ -39,8 +41,6 @@ "ms.author": "o365devx", "author": "o365devx", "ms.topic": "conceptual", - "ms.prod": "office", - "ms.technology": "open-xml", "description": "Use the Open XML SDK to programmatically create Office Word, Excel, and PowerPoint documents, and manipulate their content." }, "fileMetadata": { diff --git a/docs/general/diagnosticids.md b/docs/general/diagnosticids.md index bddef395..5094d5eb 100644 --- a/docs/general/diagnosticids.md +++ b/docs/general/diagnosticids.md @@ -5,13 +5,13 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 01/08/2025 ms.localizationpriority: high --- # Diagnostic IDs -Diagnostic IDs are used to identify APIs or patterns that can raise compiler warnings or errors. This can be done via [ObsoleteAttribute](/dotnet/api/system.obsoleteattribute.diagnosticid) or [ExperimentalAttribute](/dotnet/api/system.diagnostics.codeanalysis.experimentalattribute). These can be suppressed at the consumer level for each diagnostic id. +Diagnostic IDs are used to identify APIs or patterns that can raise compiler warnings or errors. This can be done via or . These can be suppressed at the consumer level for each diagnostic id. ## Experimental APIs @@ -19,7 +19,7 @@ Diagnostic IDs are used to identify APIs or patterns that can raise compiler war **Title**: IPackage related APIs are currently experimental -As of v3.0, a new abstraction layer was added in between `System.IO.Packaging` and `DocumentFormat.OpenXml.Packaging.OpenXmlPackage`. This is currently experimental, but can be used if needed. This will be stabalized in a future release, and may or may not require code changes. +As of v3.0, a new abstraction layer was added in between `System.IO.Packaging` and `DocumentFormat.OpenXml.Packaging.OpenXmlPackage`. This is currently experimental, but can be used if needed. This will be stabilized in a future release, and may or may not require code changes. ## Suppress warnings diff --git a/docs/general/features.md b/docs/general/features.md index 665a762d..6c3587cd 100644 --- a/docs/general/features.md +++ b/docs/general/features.md @@ -38,12 +38,13 @@ private sealed class PrivateFeature { } ``` + > [!NOTE] > The feature collection on elements is readonly. This is due to memory issues if it is made writeable. If this is needed, please engage on https://github.com/dotnet/open-xml-sdk to let us know your scenario. ## Visualizing Registered Features -The in-box implementations of the `IFeatureCollection` provide a helpful debug view so you can see what features are available and what their properties/fields are: +The in-box implementations of the provide a helpful debug view so you can see what features are available and what their properties/fields are: ![Features Debug View](../media/feature-debug-view.png) @@ -51,7 +52,7 @@ The in-box implementations of the `IFeatureCollection` provide a helpful debug v The features that are currently available are described below and at what scope they are available: -### IDisposableFeature +### This feature allows for registering actions that need to run when a package or a part is destroyed or disposed: @@ -65,7 +66,7 @@ part.Features.Get().Register(() => /* Some action that is ca Packages and parts will have their own implementations of this feature. Elements will retrieve the feature for their containing part if available. -### IPackageEventsFeature +### This feature allows getting event notifications of when a package is changed: @@ -79,7 +80,7 @@ var feature = package.Features.GetRequired(); > [!NOTE] > There may be times when the package is changed but an event is not fired. Not all areas have been identified where it would make sense to raise an event. Please file an issue if you find one. -### IPartEventsFeature +### This feature allows getting event notifications of when an event is being created. This is a feature that is added to the part or package: @@ -95,7 +96,7 @@ Generally, assume that there may be a singleton implementation for the events an > [!NOTE] > There may be times when the part is changed but an event is not fired. Not all areas have been identified where it would make sense to raise an event. Please file an issue if you find one. -### IPartRootEventsFeature +### This feature allows getting event notifications of when a part root is being modified/loaded/created/etc. This is a feature that is added to the part level feature: @@ -111,11 +112,11 @@ Generally, assume that there may be a singleton implementation for the events an > [!NOTE] > There may be times when the part root is changed but an event is not fired. Not all areas have been identified where it would make sense to raise an event. Please file an issue if you find one. -### IRandomNumberGeneratorFeature +### This feature allows for a shared service to generate random numbers and fill an array. -### IParagraphIdGeneratorFeature +### This feature allows for population and tracking of elements that contain paragraph ids. By default, this will ensure uniqueness of values and ensure that values that do exist are valid per the constraints of the standard. To use this feature: @@ -159,21 +160,3 @@ body2.AddChild(p2); Assert.NotEqual(p1.ParagraphId, p2.ParagraphId); Assert.Equal(2, shared.Count); ``` - -### IPartRootXElementFeature - -This feature allows operating on an `OpenXmlPart` by using XLinq features and directly manipulating `XElement` nodes. - -```csharp -OpenXmlPart part = GetSomePart(); - -var node = new(W.document, new XAttribute(XNamespace.Xmlns + "w", W.w), - new XElement(W.body, - new XElement(W.p, - new XElement(W.r, - new XElement(W.t, "Hello World!"))))); - -part.SetXElement(node); -``` - -This `XElement` is cached but will be kept in sync with the underlying part if it were to change. diff --git a/docs/general/how-to-add-a-new-document-part-that-receives-a-relationship-id-to-a-package.md b/docs/general/how-to-add-a-new-document-part-that-receives-a-relationship-id-to-a-package.md index 3c742e0a..296f5d06 100644 --- a/docs/general/how-to-add-a-new-document-part-that-receives-a-relationship-id-to-a-package.md +++ b/docs/general/how-to-add-a-new-document-part-that-receives-a-relationship-id-to-a-package.md @@ -11,31 +11,20 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 01/08/2025 ms.localizationpriority: medium --- # Add a new document part that receives a relationship ID to a package This topic shows how to use the classes in the Open XML SDK for -Office to add a document part (file) that receives a relationship **Id** parameter for a word +Office to add a document part (file) that receives a relationship `Id` parameter for a word processing document. ----------------------------------------------------------------------------- -## Packages and Document Parts -An Open XML document is stored as a package, whose format is defined by -[ISO/IEC 29500-2](https://www.iso.org/standard/71691.html). The -package can have multiple parts with relationships between them. The -relationship between parts controls the category of the document. A -document can be defined as a word-processing document if its -package-relationship item contains a relationship to a main document -part. If its package-relationship item contains a relationship to a -presentation part it can be defined as a presentation document. If its -package-relationship item contains a relationship to a workbook part, it -is defined as a spreadsheet document. In this how-to topic, you will use -a word-processing document package. +[!include[Structure](../includes/word/packages-and-document-parts.md)] ----------------------------------------------------------------------------- @@ -43,39 +32,51 @@ a word-processing document package. [!include[Structure](../includes/word/structure.md)] ----------------------------------------------------------------------------- -## Sample Code -The following code, adds a new document part that contains custom XML -from an external file and then populates the document part. You can call -the method **AddNewPart** by using a call like -the following code example. - -### [C#](#tab/cs-0) -```csharp - string document = @"C:\Users\Public\Documents\MyPkg1.docx"; - AddNewPart(document); -``` - -### [Visual Basic](#tab/vb-0) -```vb - Dim document As String = "C:\Users\Public\Documents\MyPkg1.docx" - AddNewPart(document) -``` + +## How the Sample Code Works + +The sample code, in this how-to, starts by passing in a parameter that represents the path to the Word document. It then creates +a new WordprocessingDocument object within a using statement. + +### [C#](#tab/cs-1) +[!code-csharp[](../../samples/word/add_a_new_part_that_receives_a_relationship_id_to_a_package/cs/Program.cs#snippet1)] + +### [Visual Basic](#tab/vb-1) +[!code-vb[](../../samples/word/add_a_new_part_that_receives_a_relationship_id_to_a_package/vb/Program.vb#snippet1)] +*** + +It then adds the MainDocumentPart part in the new word processing document, with the relationship ID, rId1. It also adds the `CustomFilePropertiesPart` part and a `CoreFilePropertiesPart` in the new word processing document. + +### [C#](#tab/cs-2) +[!code-csharp[](../../samples/word/add_a_new_part_that_receives_a_relationship_id_to_a_package/cs/Program.cs#snippet2)] + +### [Visual Basic](#tab/vb-2) +[!code-vb[](../../samples/word/add_a_new_part_that_receives_a_relationship_id_to_a_package/vb/Program.vb#snippet2)] *** +The code then adds the `DigitalSignatureOriginPart` part, the `ExtendedFilePropertiesPart` part, and the `ThumbnailPart` part in the new word processing document with realtionship IDs rId4, rId5, and rId6. -The following is the complete code example in both C\# and Visual Basic. +> [!NOTE] +> The method creates a relationship from the current document part to the new document part. This method returns the new document part. Also, you can use the method to fill the document part. + +## Sample Code + +The following code, adds a new document part that contains custom XML +from an external file and then populates the document part. Below is the +complete code example in both C\# and Visual Basic. ### [C#](#tab/cs) -[!code-csharp[](../../samples/word/add_a_new_part_that_receives_a_relationship_id_to_a_package/cs/Program.cs)] +[!code-csharp[](../../samples/word/add_a_new_part_that_receives_a_relationship_id_to_a_package/cs/Program.cs#snippet0)] ### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/word/add_a_new_part_that_receives_a_relationship_id_to_a_package/vb/Program.vb)] +[!code-vb[](../../samples/word/add_a_new_part_that_receives_a_relationship_id_to_a_package/vb/Program.vb#snippet0)] +*** ----------------------------------------------------------------------------- -## See also +## See also - [Open XML SDK class library reference](/office/open-xml/open-xml-sdk) - + diff --git a/docs/general/how-to-add-a-new-document-part-to-a-package.md b/docs/general/how-to-add-a-new-document-part-to-a-package.md index eb869c04..5cc51b22 100644 --- a/docs/general/how-to-add-a-new-document-part-to-a-package.md +++ b/docs/general/how-to-add-a-new-document-part-to-a-package.md @@ -9,7 +9,7 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 03/22/2022 +ms.date: 01/08/2025 ms.localizationpriority: medium --- @@ -17,87 +17,49 @@ ms.localizationpriority: medium This topic shows how to use the classes in the Open XML SDK for Office to add a document part (file) to a word processing document programmatically. +[!include[Structure](../includes/word/packages-and-document-parts.md)] +## Get a WordprocessingDocument object -## Packages and document parts - -An Open XML document is stored as a package, whose format is defined by [ISO/IEC 29500-2](https://www.iso.org/standard/71691.html). The package can have multiple parts with relationships between them. The relationship between parts controls the category of the document. A document can be defined as a word-processing document if its package-relationship item contains a relationship to a main document part. If its package-relationship item contains a relationship to a presentation part it can be defined as a presentation document. If its package-relationship item contains a relationship to a workbook part, it is defined as a spreadsheet document. In this how-to topic, you'll use a word-processing document package. +The code starts with opening a package file by passing a file name to one of the overloaded methods of the that takes a string and a Boolean value that specifies whether the file should be opened for editing or for read-only access. In this case, the Boolean value is `true` specifying that the file should be opened in read/write mode. -## Get a WordprocessingDocument object +### [C#](#tab/cs-1) +[!code-csharp[](../../samples/word/add_a_new_part_to_a_package/cs/Program.cs#snippet1)] -The code starts with opening a package file by passing a file name to one of the overloaded **[Open()](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.wordprocessingdocument.open.aspx)** methods of the **[DocumentFormat.OpenXml.Packaging.WordprocessingDocument](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.wordprocessingdocument.aspx)** that takes a string and a Boolean value that specifies whether the file should be opened for editing or for read-only access. In this case, the Boolean value is **true** specifying that the file should be opened in read/write mode. - -### [C#](#tab/cs-0) -```csharp - using (WordprocessingDocument wordDoc = WordprocessingDocument.Open(document, true)) - { - // Insert other code here. - } -``` - -### [Visual Basic](#tab/vb-0) -```vb - Using wordDoc As WordprocessingDocument = WordprocessingDocument.Open(document, True) - ' Insert other code here. - End Using -``` +### [Visual Basic](#tab/vb-1) +[!code-vb[](../../samples/word/add_a_new_part_to_a_package/vb/Program.vb#snippet1)] *** -The **using** statement provides a recommended alternative to the typical .Create, .Save, .Close sequence. It ensures that the **Dispose** method (internal method used by the Open XML SDK to clean up resources) is automatically called when the closing brace is reached. The block that follows the **using** statement establishes a scope for the object that is created or named in the **using** statement, in this case **wordDoc**. Because the **WordprocessingDocument** class in the Open XML SDK -automatically saves and closes the object as part of its **System.IDisposable** implementation, and because the **Dispose** method is automatically called when you exit the block; you do not have to explicitly call **Save** and **Close**, as long as you use **using**. +[!include[Using Statement](../includes/word/using-statement.md)] [!include[Structure](../includes/word/structure.md)] ## How the sample code works -After opening the document for editing, in the **using** statement, as a **WordprocessingDocument** object, the code creates a reference to the **MainDocumentPart** part and adds a new custom XML part. It then reads the contents of the external -file that contains the custom XML and writes it to the **CustomXmlPart** part. +After opening the document for editing, in the `using` statement, as a object, the code creates a reference to the `MainDocumentPart` part and adds a new custom XML part. It then reads the contents of the external +file that contains the custom XML and writes it to the `CustomXmlPart` part. > [!NOTE] > To use the new document part in the document, add a link to the document part in the relationship part for the new part. -### [C#](#tab/cs-1) -```csharp - MainDocumentPart mainPart = wordDoc.MainDocumentPart; - CustomXmlPart myXmlPart = mainPart.AddCustomXmlPart(CustomXmlPartType.CustomXml); - - using (FileStream stream = new FileStream(fileName, FileMode.Open)) - { - myXmlPart.FeedData(stream); - } -``` - -### [Visual Basic](#tab/vb-1) -```vb - Dim mainPart As MainDocumentPart = wordDoc.MainDocumentPart - - Dim myXmlPart As CustomXmlPart = mainPart.AddCustomXmlPart(CustomXmlPartType.CustomXml) +### [C#](#tab/cs-2) +[!code-csharp[](../../samples/word/add_a_new_part_to_a_package/cs/Program.cs#snippet2)] - Using stream As New FileStream(fileName, FileMode.Open) - myXmlPart.FeedData(stream) - End Using -``` +### [Visual Basic](#tab/vb-2) +[!code-vb[](../../samples/word/add_a_new_part_to_a_package/vb/Program.vb#snippet2)] *** ## Sample code -The following code adds a new document part that contains custom XML from an external file and then populates the part. To call the AddCustomXmlPart method in your program, use the following example that modifies the file "myPkg2.docx" by adding a new document part to it. +The following code adds a new document part that contains custom XML from an external file and then populates the part. To call the `AddCustomXmlPart` method in your program, use the following example that modifies a file by adding a new document part to it. -### [C#](#tab/cs-2) -```csharp - string document = @"C:\Users\Public\Documents\myPkg2.docx"; - string fileName = @"C:\Users\Public\Documents\myXML.xml"; - AddNewPart(document, fileName); -``` +### [C#](#tab/cs-3) +[!code-csharp[](../../samples/word/add_a_new_part_to_a_package/cs/Program.cs#snippet3)] -### [Visual Basic](#tab/vb-2) -```vb - Dim document As String = "C:\Users\Public\Documents\myPkg2.docx" - Dim fileName As String = "C:\Users\Public\Documents\myXML.xml" - AddNewPart(document, fileName) -``` +### [Visual Basic](#tab/vb-3) +[!code-vb[](../../samples/word/add_a_new_part_to_a_package/vb/Program.vb#snippet3)] *** @@ -107,10 +69,11 @@ The following code adds a new document part that contains custom XML from an ext Following is the complete code example in both C\# and Visual Basic. ### [C#](#tab/cs) -[!code-csharp[](../../samples/word/add_a_new_part_to_a_package/cs/Program.cs)] +[!code-csharp[](../../samples/word/add_a_new_part_to_a_package/cs/Program.cs#snippet0)] ### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/word/add_a_new_part_to_a_package/vb/Program.vb)] +[!code-vb[](../../samples/word/add_a_new_part_to_a_package/vb/Program.vb#snippet0)] +*** ## See also diff --git a/docs/general/how-to-copy-the-contents-of-an-open-xml-package-part-to-a-document-part-in-a-dif.md b/docs/general/how-to-copy-the-contents-of-an-open-xml-package-part-to-a-document-part-in-a-dif.md index 61ee8e7f..5125daf0 100644 --- a/docs/general/how-to-copy-the-contents-of-an-open-xml-package-part-to-a-document-part-in-a-dif.md +++ b/docs/general/how-to-copy-the-contents-of-an-open-xml-package-part-to-a-document-part-in-a-dif.md @@ -11,7 +11,7 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 01/08/2025 ms.localizationpriority: medium --- @@ -25,62 +25,28 @@ programmatically. -------------------------------------------------------------------------------- -## Packages and Document Parts -An Open XML document is stored as a package, whose format is defined by -[ISO/IEC 29500-2](https://www.iso.org/standard/71691.html). The -package can have multiple parts with relationships between them. The -relationship between parts controls the category of the document. A -document can be defined as a word-processing document if its -package-relationship item contains a relationship to a main document -part. If its package-relationship item contains a relationship to a -presentation part it can be defined as a presentation document. If its -package-relationship item contains a relationship to a workbook part, it -is defined as a spreadsheet document. In this how-to topic, you will use -a word-processing document package. +[!include[Structure](../includes/word/packages-and-document-parts.md)] -------------------------------------------------------------------------------- ## Getting a WordprocessingDocument Object -To open an existing document, instantiate the [WordprocessingDocument](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.wordprocessingdocument.aspx) class as shown in -the following two **using** statements. In the + +To open an existing document, instantiate the class as shown in +the following two `using` statements. In the same statement, you open the word processing file with the specified -file name by using the [Open](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.wordprocessingdocument.open.aspx) method, with the Boolean parameter. -For the source file that set the parameter to **false** to open it for read-only access. For the -target file, set the parameter to **true** in +file name by using the method, with the Boolean parameter. +For the source file that set the parameter to `false` to open it for read-only access. For the +target file, set the parameter to `true` in order to enable editing the document. -### [C#](#tab/cs-0) -```csharp - using (WordprocessingDocument wordDoc1 = WordprocessingDocument.Open(fromDocument1, false)) - using (WordprocessingDocument wordDoc2 = WordprocessingDocument.Open(toDocument2, true)) - { - // Insert other code here. - } -``` +### [C#](#tab/cs-1) +[!code-csharp[](../../samples/word/copy_the_contents_of_an_open_xml_package_part_to_a_part_a_dif/cs/Program.cs#snippet1)] -### [Visual Basic](#tab/vb-0) -```vb - Dim wordDoc1 As WordprocessingDocument = WordprocessingDocument.Open(fromDocument1, False) - Dim wordDoc2 As WordprocessingDocument = WordprocessingDocument.Open(toDocument2, True) - Using (wordDoc2) - ' Insert other code here. - End Using -``` +### [Visual Basic](#tab/vb-1) +[!code-vb[](../../samples/word/copy_the_contents_of_an_open_xml_package_part_to_a_part_a_dif/vb/Program.vb#snippet1)] *** - -The **using** statement provides a recommended -alternative to the typical .Create, .Save, .Close sequence. It ensures -that the **Dispose** method (internal method -used by the Open XML SDK to clean up resources) is automatically called -when the closing brace is reached. The block that follows the using -statement establishes a scope for the object that is created or named in -the **using** statement. Because the **WordprocessingDocument** class in the Open XML SDK -automatically saves and closes the object as part of its **System.IDisposable** implementation, and because -**Dispose** is automatically called when you -exit the block, you do not have to explicitly call **Save** and **Close**─as -long as you use **using**. - +[!include[Using Statement](../includes/word/using-statement.md)] -------------------------------------------------------------------------------- @@ -88,8 +54,9 @@ long as you use **using**. -------------------------------------------------------------------------------- ## The Theme Part + The theme part contains information about the color, font, and format of -a document. It is defined in the [ISO/IEC 29500](https://www.iso.org/standard/71691.html) specification as +a document. It is defined in the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification as follows. An instance of this part type contains information about a document's @@ -121,106 +88,70 @@ is stored in the ZIP item theme/theme1.xml: ``` -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] -------------------------------------------------------------------------------- ## How the Sample Code Works + To copy the contents of a document part in an Open XML package to a document part in a different package, the full path of the each word -processing document is passed in as a parameter to the **CopyThemeContent** method. The code then opens both -documents as **WordprocessingDocument** -objects, and creates variables that reference the **ThemePart** parts in each of the packages. +processing document is passed in as a parameter to the `CopyThemeContent` method. The code then opens both +documents as +objects, and creates variables that reference the parts in each of the packages. -### [C#](#tab/cs-1) -```csharp - public static void CopyThemeContent(string fromDocument1, string toDocument2) - { - using (WordprocessingDocument wordDoc1 = WordprocessingDocument.Open(fromDocument1, false)) - using (WordprocessingDocument wordDoc2 = WordprocessingDocument.Open(toDocument2, true)) - { - ThemePart themePart1 = wordDoc1.MainDocumentPart.ThemePart; - ThemePart themePart2 = wordDoc2.MainDocumentPart.ThemePart; -``` +### [C#](#tab/cs-2) +[!code-csharp[](../../samples/word/copy_the_contents_of_an_open_xml_package_part_to_a_part_a_dif/cs/Program.cs#snippet2)] -### [Visual Basic](#tab/vb-1) -```vb - Public Sub CopyThemeContent(ByVal fromDocument1 As String, ByVal toDocument2 As String) - Dim wordDoc1 As WordprocessingDocument = WordprocessingDocument.Open(fromDocument1, False) - Dim wordDoc2 As WordprocessingDocument = WordprocessingDocument.Open(toDocument2, True) - Using (wordDoc2) - Dim themePart1 As ThemePart = wordDoc1.MainDocumentPart.ThemePart - Dim themePart2 As ThemePart = wordDoc2.MainDocumentPart.ThemePart -``` +### [Visual Basic](#tab/vb-2) +[!code-vb[](../../samples/word/copy_the_contents_of_an_open_xml_package_part_to_a_part_a_dif/vb/Program.vb#snippet2)] *** -The code then reads the contents of the source **ThemePart** part by using a **StreamReader** object and writes to the target -**ThemePart** part by using a **StreamWriter** object. +The code then reads the contents of the source part by using a `StreamReader` object and writes to the target + part by using a . -### [C#](#tab/cs-2) -```csharp - using (StreamReader streamReader = new StreamReader(themePart1.GetStream())) - using (StreamWriter streamWriter = new StreamWriter(themePart2.GetStream(FileMode.Create))) - { - streamWriter.Write( streamReader.ReadToEnd()); - } -``` +### [C#](#tab/cs-3) +[!code-csharp[](../../samples/word/copy_the_contents_of_an_open_xml_package_part_to_a_part_a_dif/cs/Program.cs#snippet3)] -### [Visual Basic](#tab/vb-2) -```vb - Dim streamReader As StreamReader = New StreamReader(themePart1.GetStream()) - Dim streamWriter As StreamWriter = New StreamWriter(themePart2.GetStream(FileMode.Create)) - Using (streamWriter) - streamWriter.Write(streamReader.ReadToEnd) - End Using -``` +### [Visual Basic](#tab/vb-3) +[!code-vb[](../../samples/word/copy_the_contents_of_an_open_xml_package_part_to_a_part_a_dif/vb/Program.vb#snippet3)] *** -------------------------------------------------------------------------------- ## Sample Code + The following code copies the contents of one document part in an Open -XML package to a document part in a different package. To call the **CopyThemeContent** method, you can use the -following example, which copies the theme part from "MyPkg4.docx" to -"MyPkg3.docx." +XML package to a document part in a different package. To call the `CopyThemeContent` method, you can use the +following example, which copies the theme part from the packages located at `args[0]` to +one located at `args[1]`. -### [C#](#tab/cs-3) -```csharp - string fromDocument1 = @"C:\Users\Public\Documents\MyPkg4.docx"; - string toDocument2 = @"C:\Users\Public\Documents\MyPkg3.docx"; - CopyThemeContent(fromDocument1, toDocument2); -``` +### [C#](#tab/cs-4) +[!code-csharp[](../../samples/word/copy_the_contents_of_an_open_xml_package_part_to_a_part_a_dif/cs/Program.cs#snippet4)] -### [Visual Basic](#tab/vb-3) -```vb - Dim fromDocument1 As String = "C:\Users\Public\Documents\MyPkg4.docx" - Dim toDocument2 As String = "C:\Users\Public\Documents\MyPkg3.docx" - CopyThemeContent(fromDocument1, toDocument2) -``` +### [Visual Basic](#tab/vb-4) +[!code-vb[](../../samples/word/copy_the_contents_of_an_open_xml_package_part_to_a_part_a_dif/vb/Program.vb#snippet4)] *** > [!IMPORTANT] -> Before you run the program, make sure that the source document (MyPkg4.docx) has the theme part set; otherwise, an exception would be thrown. To add a theme to a document, open it in Microsoft Word 2013, click the **Page Layout** tab, click **Themes**, and select one of the available themes. +> Before you run the program, make sure that the source document has the theme part set. To add a theme to a document, +> open it in Microsoft Word, click the **Design** tab then click **Themes**, and select one of the available themes. -After running the program, you can inspect the file "MyPkg3.docx" to see -the copied theme from the file "MyPkg4.docx." +After running the program, you can inspect the file to see +the changed theme. Following is the complete sample code in both C\# and Visual Basic. ### [C#](#tab/cs) -[!code-csharp[](../../samples/word/copy_the_contents_of_an_open_xml_package_part_to_a_part_a_dif/cs/Program.cs)] +[!code-csharp[](../../samples/word/copy_the_contents_of_an_open_xml_package_part_to_a_part_a_dif/cs/Program.cs#snippet0)] ### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/word/copy_the_contents_of_an_open_xml_package_part_to_a_part_a_dif/vb/Program.vb)] +[!code-vb[](../../samples/word/copy_the_contents_of_an_open_xml_package_part_to_a_part_a_dif/vb/Program.vb#snippet0)] +*** -------------------------------------------------------------------------------- ## See also - - [Open XML SDK class library reference](/office/open-xml/open-xml-sdk) - - - - diff --git a/docs/general/how-to-create-a-package.md b/docs/general/how-to-create-a-package.md index a4f62cdc..2d26e059 100644 --- a/docs/general/how-to-create-a-package.md +++ b/docs/general/how-to-create-a-package.md @@ -11,7 +11,7 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 01/03/2025 ms.localizationpriority: medium --- @@ -19,77 +19,41 @@ ms.localizationpriority: medium This topic shows how to use the classes in the Open XML SDK for Office to programmatically create a word processing document package -from content in the form of **WordprocessingML** XML markup. - - - -## Packages and Document Parts - -An Open XML document is stored as a package, whose format is defined by -[ISO/IEC 29500-2](https://www.iso.org/standard/71691.html). The -package can have multiple parts with relationships between them. The -relationship between parts controls the category of the document. A -document can be defined as a word-processing document if its -package-relationship item contains a relationship to a main document -part. If its package-relationship item contains a relationship to a -presentation part it can be defined as a presentation document. If its -package-relationship item contains a relationship to a workbook part, it -is defined as a spreadsheet document. In this how-to topic, you will use -a word-processing document package. +from content in the form of `WordprocessingML` XML markup. +[!include[Structure](../includes/word/packages-and-document-parts.md)] ## Getting a WordprocessingDocument Object -In the Open XML SDK, the [WordprocessingDocument](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.wordprocessingdocument.aspx) class represents a Word document package. To create a Word document, you create an instance -of the **WordprocessingDocument** class and +In the Open XML SDK, the class represents a Word document package. To create a Word document, you create an instance +of the class and populate it with parts. At a minimum, the document must have a main document part that serves as a container for the main text of the -document. The text is represented in the package as XML using **WordprocessingML** markup. +document. The text is represented in the package as XML using `WordprocessingML` markup. -To create the class instance you call the [Create(String, WordprocessingDocumentType)](https://msdn.microsoft.com/library/office/cc535610.aspx) -method. Several **Create** methods are -provided, each with a different signature. The sample code in this topic -uses the **Create** method with a signature -that requires two parameters. The first parameter takes a full path +To create the class instance you call . Several methods are +provided, each with a different signature. The first parameter takes a full path string that represents the document that you want to create. The second -parameter is a member of the [WordprocessingDocumentType](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessingdocumenttype.aspx) enumeration. +parameter is a member of the enumeration. This parameter represents the type of document. For example, there is a -different member of the [WordProcessingDocumentType](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessingdocumenttype.aspx) enumeration for each +different member of the enumeration for each of document, template, and the macro enabled variety of document and template. > [!NOTE] -> Carefully select the appropriate **WordProcessingDocumentType** and verify that the persisted file has the correct, matching file extension. If the **WordProcessingDocumentType** does not match the file extension, an error occurs when you open the file in Microsoft Word. The code that calls the **Create** method is part of a **using** statement followed by a bracketed block, as shown in the following code example. - -### [C#](#tab/cs-0) -```csharp - using (WordprocessingDocument wordDoc = WordprocessingDocument.Create(document, WordprocessingDocumentType.Document)) - { - // Insert other code here. - } -``` - -### [Visual Basic](#tab/vb-0) -```vb - Using wordDoc As WordprocessingDocument = WordprocessingDocument.Create(document, WordprocessingDocumentType.Document) - ' Insert other code here. - End Using -``` -*** +> Carefully select the appropriate and verify that the persisted file has the correct, matching file extension. If the does not match the file extension, an error occurs when you open the file in Microsoft Word. +### [C#](#tab/cs-1) +[!code-csharp[](../../samples/word/create_a_package/cs/Program.cs#snippet1)] -The **using** statement provides a recommended -alternative to the typical .Create, .Save, .Close sequence. It ensures -that the **Dispose** () method (internal method -used by the Open XML SDK to clean up resources) is automatically called -when the closing bracket is reached. The block that follows the **using** statement establishes a scope for the -object that is created or named in the **using** statement, in this case **wordDoc**. Because the **WordprocessingDocument** class in the Open XML SDK -automatically saves and closes the object as part of its **System.IDisposable** implementation, and because -**Dispose** is automatically called when you exit the bracketed block, you do not have to explicitly call **Save** and **Close**─as -long as you use **using**. +### [Visual Basic](#tab/vb-1) +[!code-vb[](../../samples/word/create_a_package/vb/Program.vb#snippet1)] +*** + +[!include[Using Statement](../includes/word/using-statement.md)] Once you have created the Word document package, you can add parts to -it. To add the main document part you call the [AddMainDocumentPart()](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.wordprocessingdocument.addmaindocumentpart.aspx) method of the **WordprocessingDocument** class. Having done that, +it. To add the main document part you call . Having done that, you can set about adding the document structure and text. [!include[Structure](../includes/word/structure.md)] @@ -98,39 +62,21 @@ you can set about adding the document structure and text. The following is the complete code sample that you can use to create an Open XML word processing document package from XML content in the form -of **WordprocessingML** markup. In your -program, you can invoke the method **CreateNewWordDocument** by using the following -call: - -### [C#](#tab/cs-1) -```csharp - CreateNewWordDocument(@"C:\Users\Public\Documents\MyPkg4.docx"); -``` +of `WordprocessingML` markup. -### [Visual Basic](#tab/vb-1) -```vb - CreateNewWordDocument("C:\Users\Public\Documents\MyPkg4.docx") -``` -*** - - -After you run the program, open the created file "myPkg4.docx" and +After you run the program, open the created file and examine its content; it should be one paragraph that contains the phrase "Hello world!" Following is the complete sample code in both C\# and Visual Basic. ### [C#](#tab/cs) -[!code-csharp[](../../samples/word/create_a_package/cs/Program.cs)] +[!code-csharp[](../../samples/word/create_a_package/cs/Program.cs#snippet0)] ### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/word/create_a_package/vb/Program.vb)] +[!code-vb[](../../samples/word/create_a_package/vb/Program.vb#snippet0)] +*** ## See also - - - [Open XML SDK class library reference](/office/open-xml/open-xml-sdk) - - - diff --git a/docs/general/how-to-get-the-contents-of-a-document-part-from-a-package.md b/docs/general/how-to-get-the-contents-of-a-document-part-from-a-package.md index e022e650..8c1fe0b6 100644 --- a/docs/general/how-to-get-the-contents-of-a-document-part-from-a-package.md +++ b/docs/general/how-to-get-the-contents-of-a-document-part-from-a-package.md @@ -11,7 +11,7 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 01/08/2025 ms.localizationpriority: high --- # Get the contents of a document part from a package @@ -23,59 +23,28 @@ document programmatically. -------------------------------------------------------------------------------- -## Packages and Document Parts -An Open XML document is stored as a package, whose format is defined by -[ISO/IEC 29500-2](https://www.iso.org/standard/71691.html). The -package can have multiple parts with relationships between them. The -relationship between parts controls the category of the document. A -document can be defined as a word-processing document if its -package-relationship item contains a relationship to a main document -part. If its package-relationship item contains a relationship to a -presentation part it can be defined as a presentation document. If its -package-relationship item contains a relationship to a workbook part, it -is defined as a spreadsheet document. In this how-to topic, you will use -a word-processing document package. +[!include[Structure](../includes/word/packages-and-document-parts.md)] --------------------------------------------------------------------------------- ## Getting a WordprocessingDocument Object + The code starts with opening a package file by passing a file name to -one of the overloaded [Open()](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.wordprocessingdocument.open.aspx) methods (Visual Basic .NET Shared -method or C\# static method) of the [WordprocessingDocument](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.wordprocessingdocument.aspx) class that takes a +one of the overloaded methods (Visual Basic .NET Shared +method or C\# static method) of the class that takes a string and a Boolean value that specifies whether the file should be opened in read/write mode or not. In this case, the Boolean value is -**false** specifying that the file should be +`false` specifying that the file should be opened in read-only mode to avoid accidental changes. -### [C#](#tab/cs-0) -```csharp - // Open a Wordprocessing document for editing. - using (WordprocessingDocument wordDoc = WordprocessingDocument.Open(document, false)) - { - // Insert other code here. - } -``` +### [C#](#tab/cs-1) +[!code-csharp[](../../samples/word/get_the_contents_of_a_part_from_a_package/cs/Program.cs#snippet1)] -### [Visual Basic](#tab/vb-0) -```vb - ' Open a Wordprocessing document for editing. - Using wordDoc As WordprocessingDocument = WordprocessingDocument.Open(document, False) - ' Insert other code here. - End Using -``` +### [Visual Basic](#tab/vb-1) +[!code-vb[](../../samples/word/get_the_contents_of_a_part_from_a_package/vb/Program.vb#snippet1)] *** - -The **using** statement provides a recommended -alternative to the typical .Create, .Save, .Close sequence. It ensures -that the **Dispose** method (internal method -used by the Open XML SDK to clean up resources) is automatically called -when the closing brace is reached. The block that follows the **using** statement establishes a scope for the -object that is created or named in the **using** statement, in this case **wordDoc**. Because the **WordprocessingDocument** class in the Open XML SDK -automatically saves and closes the object as part of its **System.IDisposable** implementation, and because -the **Dispose** method is automatically called -when you exit the block; you do not have to explicitly call **Save** and **Close**─as -long as you use using. +[!include[Using Statement](../includes/word/using-statement.md)] --------------------------------------------------------------------------------- @@ -84,9 +53,10 @@ long as you use using. -------------------------------------------------------------------------------- ## Comments Element + In this how-to, you are going to work with comments. Therefore, it is -useful to familiarize yourself with the structure of the \<**comments**\> element. The following information -from the [ISO/IEC 29500](https://www.iso.org/standard/71691.html) +useful to familiarize yourself with the structure of the `` element. The following information +from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification can be useful when working with this element. This element specifies all of the comments defined in the current @@ -106,7 +76,7 @@ document: The **comments** element contains the single comment specified by this document in this example. -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] The following XML schema fragment defines the contents of this element. @@ -120,92 +90,57 @@ The following XML schema fragment defines the contents of this element. -------------------------------------------------------------------------------- ## How the Sample Code Works -After you have opened the source file for reading, you create a **mainPart** object by instantiating the **MainDocumentPart**. Then you can create a reference -to the **WordprocessingCommentsPart** part of + +After you have opened the source file for reading, you create a `mainPart` object by instantiating the `MainDocumentPart`. Then you can create a reference +to the `WordprocessingCommentsPart` part of the document. -### [C#](#tab/cs-1) -```csharp - // To get the contents of a document part. - public static string GetCommentsFromDocument(string document) - { - string comments = null; - - using (WordprocessingDocument wordDoc = WordprocessingDocument.Open(document, true)) - { - MainDocumentPart mainPart = wordDoc.MainDocumentPart; - WordprocessingCommentsPart WordprocessingCommentsPart = mainPart.WordprocessingCommentsPart; -``` +### [C#](#tab/cs-2) +[!code-csharp[](../../samples/word/get_the_contents_of_a_part_from_a_package/cs/Program.cs#snippet2)] -### [Visual Basic](#tab/vb-1) -```vb - ' To get the contents of a document part. - Public Shared Function GetCommentsFromDocument(ByVal document As String) As String - Dim comments As String = Nothing - - Using wordDoc As WordprocessingDocument = WordprocessingDocument.Open(document, True) - Dim mainPart As MainDocumentPart = wordDoc.MainDocumentPart - Dim WordprocessingCommentsPart As WordprocessingCommentsPart = mainPart.WordprocessingCommentsPart -``` +### [Visual Basic](#tab/vb-2) +[!code-vb[](../../samples/word/get_the_contents_of_a_part_from_a_package/vb/Program.vb#snippet2)] *** -You can then use a **StreamReader** object to -read the contents of the **WordprocessingCommentsPart** part of the document +You can then use a `StreamReader` object to +read the contents of the `WordprocessingCommentsPart` part of the document and return its contents. -### [C#](#tab/cs-2) -```csharp - using (StreamReader streamReader = new StreamReader(WordprocessingCommentsPart.GetStream())) - { - comments = streamReader.ReadToEnd(); - } - } - return comments; -``` +### [C#](#tab/cs-3) +[!code-csharp[](../../samples/word/get_the_contents_of_a_part_from_a_package/cs/Program.cs#snippet3)] -### [Visual Basic](#tab/vb-2) -```vb - Using streamReader As New StreamReader(WordprocessingCommentsPart.GetStream()) - comments = streamReader.ReadToEnd() - End Using - Return comments -``` +### [Visual Basic](#tab/vb-3) +[!code-vb[](../../samples/word/get_the_contents_of_a_part_from_a_package/vb/Program.vb#snippet3)] *** -------------------------------------------------------------------------------- ## Sample Code -The following code retrieves the contents of a **WordprocessingCommentsPart** part contained in a -**WordProcessing** document package. You can -run the program by calling the **GetCommentsFromDocument** method as shown in the +The following code retrieves the contents of a `WordprocessingCommentsPart` part contained in a +`WordProcessing` document package. You can +run the program by calling the `GetCommentsFromDocument` method as shown in the following example. -### [C#](#tab/cs-3) -```csharp - string document = @"C:\Users\Public\Documents\MyPkg5.docx"; - GetCommentsFromDocument(document); -``` +### [C#](#tab/cs-4) +[!code-csharp[](../../samples/word/get_the_contents_of_a_part_from_a_package/cs/Program.cs#snippet4)] -### [Visual Basic](#tab/vb-3) -```vb - Dim document As String = "C:\Users\Public\Documents\MyPkg5.docx" - GetCommentsFromDocument(document) -``` +### [Visual Basic](#tab/vb-4) +[!code-vb[](../../samples/word/get_the_contents_of_a_part_from_a_package/vb/Program.vb#snippet4)] *** - Following is the complete code example in both C\# and Visual Basic. ### [C#](#tab/cs) -[!code-csharp[](../../samples/word/get_the_contents_of_a_part_from_a_package/cs/Program.cs)] +[!code-csharp[](../../samples/word/get_the_contents_of_a_part_from_a_package/cs/Program.cs#snippet0)] ### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/word/get_the_contents_of_a_part_from_a_package/vb/Program.vb)] +[!code-vb[](../../samples/word/get_the_contents_of_a_part_from_a_package/vb/Program.vb#snippet0)] +*** -------------------------------------------------------------------------------- ## See also [Open XML SDK class library -reference](https://msdn.microsoft.com/library/36c8a76e-ce1b-5959-7e85-5d77db7f46d6(Office.15).aspx) +reference](/office/open-xml/open-xml-sdk) diff --git a/docs/general/how-to-remove-a-document-part-from-a-package.md b/docs/general/how-to-remove-a-document-part-from-a-package.md index e2a4c432..8d594ea4 100644 --- a/docs/general/how-to-remove-a-document-part-from-a-package.md +++ b/docs/general/how-to-remove-a-document-part-from-a-package.md @@ -11,7 +11,7 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 01/03/2025 ms.localizationpriority: medium --- # Remove a document part from a package @@ -23,58 +23,29 @@ programmatically. -------------------------------------------------------------------------------- -## Packages and Document Parts -An Open XML document is stored as a package, whose format is defined by -[ISO/IEC 29500-2](https://www.iso.org/standard/71691.html). The -package can have multiple parts with relationships between them. The -relationship between parts controls the category of the document. A -document can be defined as a word-processing document if its -package-relationship item contains a relationship to a main document -part. If its package-relationship item contains a relationship to a -presentation part it can be defined as a presentation document. If its -package-relationship item contains a relationship to a workbook part, it -is defined as a spreadsheet document. In this how-to topic, you will use -a word-processing document package. +[!include[Structure](../includes/word/packages-and-document-parts.md)] --------------------------------------------------------------------------------- ## Getting a WordprocessingDocument Object + The code example starts with opening a package file by passing a file -name as an argument to one of the overloaded [Open()](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.wordprocessingdocument.open.aspx) methods of the [DocumentFormat.OpenXml.Packaging.WordprocessingDocument](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.wordprocessingdocument.aspx) +name as an argument to one of the overloaded methods of the + that takes a string and a Boolean value that specifies whether the file should be opened in read/write mode or not. In this case, the Boolean -value is **true** specifying that the file +value is `true` specifying that the file should be opened in read/write mode. -### [C#](#tab/cs-0) -```csharp - // Open a Wordprocessing document for editing. - using (WordprocessingDocument wordDoc = WordprocessingDocument.Open(document, true)) - { - // Insert other code here. - } -``` +### [C#](#tab/cs-1) +[!code-csharp[](../../samples/word/remove_a_part_from_a_package/cs/Program.cs#snippet1)] -### [Visual Basic](#tab/vb-0) -```vb - ' Open a Wordprocessing document for editing. - Using wordDoc As WordprocessingDocument = WordprocessingDocument.Open(document, True) - ' Insert other code here. - End Using -``` +### [Visual Basic](#tab/vb-1) +[!code-vb[](../../samples/word/remove_a_part_from_a_package/vb/Program.vb#snippet1)] *** -The **using** statement provides a recommended -alternative to the typical .Create, .Save, .Close sequence. It ensures -that the **Dispose** method (internal method -used by the Open XML SDK to clean up resources) is automatically called -when the closing brace is reached. The block that follows the **using** statement establishes a scope for the -object that is created or named in the **using** statement, in this case **wordDoc**. Because the **WordprocessingDocument** class in the Open XML SDK -automatically saves and closes the object as part of its **System.IDisposable** implementation, and because -the **Dispose** method is automatically called -when you exit the block; you do not have to explicitly call **Save** and **Close**─as -long as you use **using**. +[!include[Using Statement](../includes/word/using-statement.md)] --------------------------------------------------------------------------------- @@ -83,9 +54,8 @@ long as you use **using**. -------------------------------------------------------------------------------- ## Settings Element -The following text from the [ISO/IEC -29500](https://www.iso.org/standard/71691.html) specification -introduces the settings element in a **PresentationML** package. +The following text from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification +introduces the settings element in a `PresentationML` package. > This element specifies the settings that are applied to a > WordprocessingML document. This element is the root element of the @@ -106,65 +76,37 @@ introduces the settings element in a **PresentationML** package. > automatic tab stop increments of 0.5" using the **defaultTabStop** element, and no character level > white space compression using the **characterSpacingControl** element. > -> © ISO/IEC29500: 2008. +> © [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] -------------------------------------------------------------------------------- ## How the Sample Code Works -After you have opened the document, in the **using** statement, as a **WordprocessingDocument** object, you create a -reference to the **DocumentSettingsPart** part. + +After you have opened the document, in the `using` statement, as a object, you create a +reference to the `DocumentSettingsPart` part. You can then check if that part exists, if so, delete that part from the -package. In this instance, the **settings.xml** +package. In this instance, the `settings.xml` part is removed from the package. -### [C#](#tab/cs-1) -```csharp - MainDocumentPart mainPart = wordDoc.MainDocumentPart; - if (mainPart.DocumentSettingsPart != null) - { - mainPart.DeletePart(mainPart.DocumentSettingsPart); - } -``` +### [C#](#tab/cs-2) +[!code-csharp[](../../samples/word/remove_a_part_from_a_package/cs/Program.cs#snippet2)] -### [Visual Basic](#tab/vb-1) -```vb - Dim mainPart As MainDocumentPart = wordDoc.MainDocumentPart - If mainPart.DocumentSettingsPart IsNot Nothing Then - mainPart.DeletePart(mainPart.DocumentSettingsPart) - End If -``` +### [Visual Basic](#tab/vb-2) +[!code-vb[](../../samples/word/remove_a_part_from_a_package/vb/Program.vb#snippet2)] *** -------------------------------------------------------------------------------- ## Sample Code -The following code removes a document part from a package. To run the -program, call the method **RemovePart** like -this example. - -### [C#](#tab/cs-2) -```csharp - string document = @"C:\Users\Public\Documents\MyPkg6.docx"; - RemovePart(document); -``` - -### [Visual Basic](#tab/vb-2) -```vb - Dim document As String = "C:\Users\Public\Documents\MyPkg6.docx" - RemovePart(document) -``` -*** - -> [!NOTE] -> Before running the program on the test file, "MyPkg6.docs," for example, open the file by using the Open XML SDK Productivity Tool for Microsoft Office and examine its structure. After running the program, examine the file again, and you will notice that the **DocumentSettingsPart** part was removed. Following is the complete code example in both C\# and Visual Basic. ### [C#](#tab/cs) -[!code-csharp[](../../samples/word/remove_a_part_from_a_package/cs/Program.cs)] +[!code-csharp[](../../samples/word/remove_a_part_from_a_package/cs/Program.cs#snippet0)] ### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/word/remove_a_part_from_a_package/vb/Program.vb)] +[!code-vb[](../../samples/word/remove_a_part_from_a_package/vb/Program.vb#snippet0)] +*** -------------------------------------------------------------------------------- ## See also diff --git a/docs/general/how-to-replace-the-theme-part-in-a-word-processing-document.md b/docs/general/how-to-replace-the-theme-part-in-a-word-processing-document.md index 8ed5b408..5d1b1527 100644 --- a/docs/general/how-to-replace-the-theme-part-in-a-word-processing-document.md +++ b/docs/general/how-to-replace-the-theme-part-in-a-word-processing-document.md @@ -11,7 +11,7 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 01/08/2025 ms.localizationpriority: medium --- # Replace the theme part in a word processing document @@ -20,79 +20,43 @@ This topic shows how to use the classes in the Open XML SDK for Office to programmatically replace a document part in a word processing document. - - -## Packages and Document Parts - -An Open XML document is stored as a package, whose format is defined by -[ISO/IEC 29500-2](https://www.iso.org/standard/71691.html). The -package can have multiple parts with relationships between them. The -relationship between parts controls the category of the document. A -document can be defined as a word-processing document if its -package-relationship item contains a relationship to a main document -part. If its package-relationship item contains a relationship to a -presentation part it can be defined as a presentation document. If its -package-relationship item contains a relationship to a workbook part, it -is defined as a spreadsheet document. In this how-to topic, you will use -a word-processing document package. +[!include[Structure](../includes/word/packages-and-document-parts.md)] ## Getting a WordprocessingDocument Object In the sample code, you start by opening the word processing file by -instantiating the [WordprocessingDocument](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.wordprocessingdocument.aspx) class as shown in -the following **using** statement. In the same +instantiating the class as shown in +the following `using` statement. In the same statement, you open the word processing file *document* by using the -[Open](https://msdn.microsoft.com/library/office/cc562234.aspx) method, with the Boolean parameter set -to **true** to enable editing the document. - -### [C#](#tab/cs-0) -```csharp - using (WordprocessingDocument wordDoc = - WordprocessingDocument.Open(document, true)) - { - // Insert other code here. - } -``` + method, with the Boolean parameter set +to `true` to enable editing the document. -### [Visual Basic](#tab/vb-0) -```vb - Using wordDoc As WordprocessingDocument = WordprocessingDocument.Open(document, True) - ' Insert other code here. - End Using -``` -*** +### [C#](#tab/cs-1) +[!code-csharp[](../../samples/word/replace_the_theme_part/cs/Program.cs#snippet1)] +### [Visual Basic](#tab/vb-1) +[!code-vb[](../../samples/word/replace_the_theme_part/vb/Program.vb#snippet1)] +*** -The **using** statement provides a recommended -alternative to the typical .Open, .Save, .Close sequence. It ensures -that the **Dispose** method (internal method -used by the Open XML SDK to clean up resources) is automatically called -when the closing brace is reached. The block that follows the **using** statement establishes a scope for the -object that is created or named in the **using** statement, in this case *wordDoc*. Because -the **WordprocessingDocument** class in the -Open XML SDK automatically saves and closes the object as part of its -**System.IDisposable** implementation, and -because **Dispose** is automatically called -when you exit the block, you do not have to explicitly call **Save** and **Close**─as -long as you use **using**. +[!include[Using Statement](../includes/word/using-statement.md)] ## How to Change Theme in a Word Package If you would like to change the theme in a Word document, click the -ribbon **Page Layout** and then click **Themes**. The **Themes** pull-down -menu opens. To choose one of the built it themes and apply it to the +ribbon **Design** and then click **Themes**. The **Themes** pull-down +menu opens. To choose one of the built-in themes and apply it to the Word document, click the theme icon. You can also use the option **Browse for Themes...** to locate and apply a theme file in your computer. -## The Structure of the Theme Element +## The Structure of the Theme Element -The theme element constitutes of color, font, and format schemes. In +The theme element is constituted of color, font, and format schemes. In this how-to you learn how to change the theme programmatically. Therefore, it is useful to familiarize yourself with the theme element. -The following information from the [ISO/IEC 29500](https://www.iso.org/standard/71691.html) specification can +The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification can be useful when working with this element. This element defines the root level complex type associated with a @@ -107,28 +71,29 @@ how a theme can affect font, colors, backgrounds, fills, and effects for different objects in a presentation. end example] ![Theme sample](../media/a-theme01.gif) + In this example, we see how a theme can affect font, colors, backgrounds, fills, and effects for different objects in a presentation. *end example*] -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] The following table lists the possible child types of the Theme class. | PresentationML Element | Open XML SDK Class | Description | |---|---|---| -| custClrLst | [CustomColorList](https://msdn.microsoft.com/library/office/documentformat.openxml.drawing.customcolorlist.aspx) |Custom Color List | -| extLst | [ExtensionList](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.extensionlist.aspx) | Extension List | -| extraClrSchemeLst | [ExtraColorSchemeList](https://msdn.microsoft.com/library/office/documentformat.openxml.drawing.theme.extracolorschemelist.aspx) | Extra Color Scheme List | -| objectDefaults | [ObjectDefaults](https://msdn.microsoft.com/library/office/documentformat.openxml.drawing.theme.objectdefaults.aspx) | Object Defaults | -| themeElements | [ThemeElements](https://msdn.microsoft.com/library/office/documentformat.openxml.drawing.theme.themeelements.aspx) | Theme Elements | +| `` | |Custom Color List | +| `` | | Extension List | +| `` | | Extra Color Scheme List | +| `` | | Object Defaults | +| `` | | Theme Elements | The following XML Schema fragment defines the four parts of the theme -element. The **themeElements** element is the +element. The `themeElements` element is the piece that holds the main formatting defined within the theme. The other parts provide overrides, defaults, and additions to the information -contained in **themeElements**. The complex -type defining a theme, **CT\_OfficeStyleSheet**, is defined in the following +contained in `themeElements`. The complex +type defining a theme, `CT_OfficeStyleSheet`, is defined in the following manner: ```xml @@ -144,68 +109,32 @@ manner: ``` -This complex type also holds a **CT\_OfficeArtExtensionList**, which is used for +This complex type also holds a `CT_OfficeArtExtensionList`, which is used for future extensibility of this complex type. ## How the Sample Code Works -After opening the file, you can instantiate the **MainDocumentPart** in the *wordDoc* object, and +After opening the file, you can instantiate the `MainDocumentPart` in the `wordDoc` object, and delete the old theme part. -### [C#](#tab/cs-1) -```csharp - public static void ReplaceTheme(string document, string themeFile) - { - using (WordprocessingDocument wordDoc = - WordprocessingDocument.Open(document, true)) - { - MainDocumentPart mainPart = wordDoc.MainDocumentPart; - - // Delete the old document part. - mainPart.DeletePart(mainPart.ThemePart); -``` - -### [Visual Basic](#tab/vb-1) -```vb - Public Shared Sub ReplaceTheme(ByVal document As String, ByVal themeFile As String) - Using wordDoc As WordprocessingDocument = WordprocessingDocument.Open(document, True) - Dim mainPart As MainDocumentPart = wordDoc.MainDocumentPart +### [C#](#tab/cs-2) +[!code-csharp[](../../samples/word/replace_the_theme_part/cs/Program.cs#snippet2)] - ' Delete the old document part. - mainPart.DeletePart(mainPart.ThemePart) -``` +### [Visual Basic](#tab/vb-2) +[!code-vb[](../../samples/word/replace_the_theme_part/vb/Program.vb#snippet2)] *** -You can then create add a new **ThemePart** -object and add it to the **MainDocumentPart** -object. Then you add content by using a **StreamReader** and **StreamWriter** objects to copy the theme from the -*themeFile* to the **ThemePart** object. +You can then create add a new +object and add it to the `MainDocumentPart` +object. Then you add content by using a `StreamReader` and objects to copy the theme from the +`themeFile` to the object. -### [C#](#tab/cs-2) -```csharp - // Add a new document part and then add content. - ThemePart themePart = mainPart.AddNewPart(); - - using (StreamReader streamReader = new StreamReader(themeFile)) - using (StreamWriter streamWriter = - new StreamWriter(themePart.GetStream(FileMode.Create))) - { - streamWriter.Write(streamReader.ReadToEnd()); - } -``` +### [C#](#tab/cs-3) +[!code-csharp[](../../samples/word/replace_the_theme_part/cs/Program.cs#snippet3)] -### [Visual Basic](#tab/vb-2) -```vb - ' Add a new document part and then add content. - Dim themePart As ThemePart = mainPart.AddNewPart(Of ThemePart)() - - Using streamReader As New StreamReader(themeFile) - Using streamWriter As New StreamWriter(themePart.GetStream(FileMode.Create)) - streamWriter.Write(streamReader.ReadToEnd()) - End Using - End Using -``` +### [Visual Basic](#tab/vb-3) +[!code-vb[](../../samples/word/replace_the_theme_part/vb/Program.vb#snippet3)] *** @@ -216,36 +145,28 @@ in a word processing document with the theme part from another package. The theme file passed as the second argument must be a valid theme part in XML format (for example, Theme1.xml). You can extract this part from an existing document or theme file (.THMX) that has been renamed to be a -.Zip file. To call the method **ReplaceTheme** +.Zip file. To call the method `ReplaceTheme` you can use the following call example to copy the theme from the file -"Theme1.xml" to the file "MyPkg7.docx." +from `arg[1]` and to the file located at `arg[0]` -### [C#](#tab/cs-3) -```csharp - string document = @"C:\Users\Public\Documents\\MyPkg7.docx"; - string themeFile = @"C:\Users\Public\Documents\Theme1.xml"; - ReplaceTheme(document, themeFile); -``` +### [C#](#tab/cs-4) +[!code-csharp[](../../samples/word/replace_the_theme_part/cs/Program.cs#snippet4)] -### [Visual Basic](#tab/vb-3) -```vb - Dim document As String = "C:\Users\Public\Documents\\MyPkg7.docx" - Dim themeFile As String = "C:\Users\Public\Documents\Theme1.xml" - ReplaceTheme(document, themeFile) -``` +### [Visual Basic](#tab/vb-4) +[!code-vb[](../../samples/word/replace_the_theme_part/vb/Program.vb#snippet4)] *** -After you run the program open the Word file and notice the change in -font. +After you run the program open the Word file and notice the new theme changes. Following is the complete sample code in both C\# and Visual Basic. ### [C#](#tab/cs) -[!code-csharp[](../../samples/word/replace_the_theme_part/cs/Program.cs)] +[!code-csharp[](../../samples/word/replace_the_theme_part/cs/Program.cs#snippet0)] ### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/word/replace_the_theme_part/vb/Program.vb)] +[!code-vb[](../../samples/word/replace_the_theme_part/vb/Program.vb#snippet0)] +*** ## See also diff --git a/docs/general/how-to-search-and-replace-text-in-a-document-part.md b/docs/general/how-to-search-and-replace-text-in-a-document-part.md index cfdfbe19..4c72808a 100644 --- a/docs/general/how-to-search-and-replace-text-in-a-document-part.md +++ b/docs/general/how-to-search-and-replace-text-in-a-document-part.md @@ -23,85 +23,51 @@ processing document. -------------------------------------------------------------------------------- -## Packages and Document Parts -An Open XML document is stored as a package, whose format is defined by -[ISO/IEC 29500-2](https://www.iso.org/standard/71691.html). The -package can have multiple parts with relationships between them. The -relationship between parts controls the category of the document. A -document can be defined as a word-processing document if its -package-relationship item contains a relationship to a main document -part. If its package-relationship item contains a relationship to a -presentation part it can be defined as a presentation document. If its -package-relationship item contains a relationship to a workbook part, it -is defined as a spreadsheet document. In this how-to topic, you will use -a word-processing document package. +[!include[Structure](../includes/word/packages-and-document-parts.md)] --------------------------------------------------------------------------------- -## Getting a WordprocessingDocument Object +## Getting a WordprocessingDocument Object + In the sample code, you start by opening the word processing file by -instantiating the **[WordprocessingDocument](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.wordprocessingdocument.aspx)** class as shown in -the following **using** statement. In the same -statement, you open the word processing file *document* by using the -**[Open](https://msdn.microsoft.com/library/office/cc562234.aspx)** method, with the Boolean parameter set -to **true** to enable editing the document. - -### [C#](#tab/cs-0) -```csharp - using (WordprocessingDocument wordDoc = - WordprocessingDocument.Open(document, true)) - { - // Insert other code here. - } -``` - -### [Visual Basic](#tab/vb-0) -```vb - Using wordDoc As WordprocessingDocument = WordprocessingDocument.Open(document, True) - ' Insert other code here. - End Using -``` +instantiating the class as shown in +the following `using` statement. In the same +statement, you open the word processing file `document` by using the + method, with the Boolean parameter set +to `true` to enable editing the document. + +### [C#](#tab/cs-1) +[!code-csharp[](../../samples/word/search_and_replace_text_a_part/cs/Program.cs#snippet1)] + +### [Visual Basic](#tab/vb-1) +[!code-vb[](../../samples/word/search_and_replace_text_a_part/vb/Program.vb#snippet1)] *** -The **using** statement provides a recommended -alternative to the typical .Open, .Save, .Close sequence. It ensures -that the **Dispose** method (internal method -used by the Open XML SDK to clean up resources) is automatically called -when the closing brace is reached. The block that follows the **using** statement establishes a scope for the -object that is created or named in the **using** statement, in this case *wordDoc*. Because -the **WordprocessingDocument** class in the -Open XML SDK automatically saves and closes the object as part of its -**System.IDisposable** implementation, and -because **Dispose** is automatically called -when you exit the block, you do not have to explicitly call **Save** and **Close**─as -long as you use **using**. +[!include[Using Statement](../includes/word/using-statement.md)] -------------------------------------------------------------------------------- -## Sample Code +## Sample Code + The following example demonstrates a quick and easy way to search and replace. It may not be reliable because it retrieves the XML document in string format. Depending on the regular expression you might unintentionally replace XML tags and corrupt the document. If you simply want to search a document, but not replace the contents you can use -*MainDocumentPart.Document.InnerText*. +`MainDocumentPart.Document.InnerText`. This example also shows how to use a regular expression to search and -replace the text value, "Hello world!" stored in a word processing file -named "MyPkg8.docx," with the value "Hi Everyone!". To call the method -**SearchAndReplace**, you can use the following +replace the text value, "Hello World!" stored in a word processing file +with the value "Hi Everyone!". To call the method +`SearchAndReplace`, you can use the following example. -### [C#](#tab/cs-1) -```csharp - SearchAndReplace(@"C:\Users\Public\Documents\MyPkg8.docx"); -``` +### [C#](#tab/cs-2) +[!code-csharp[](../../samples/word/search_and_replace_text_a_part/cs/Program.cs#snippet2)] -### [Visual Basic](#tab/vb-1) -```vb - SearchAndReplace("C:\Users\Public\Documents\MyPkg8.docx") -``` +### [Visual Basic](#tab/vb-2) +[!code-vb[](../../samples/word/search_and_replace_text_a_part/vb/Program.vb#snippet2)] *** @@ -111,15 +77,16 @@ the text, "Hello world!" The following is the complete sample code in both C\# and Visual Basic. ### [C#](#tab/cs) -[!code-csharp[](../../samples/word/search_and_replace_text_a_part/cs/Program.cs)] +[!code-csharp[](../../samples/word/search_and_replace_text_a_part/cs/Program.cs#snippet0)] ### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/word/search_and_replace_text_a_part/vb/Program.vb)] +[!code-vb[](../../samples/word/search_and_replace_text_a_part/vb/Program.vb#snippet0)] +*** -------------------------------------------------------------------------------- -## See also +## See also - [Open XML SDK class library reference](/office/open-xml/open-xml-sdk) -[Regular Expressions](https://msdn.microsoft.com/library/hs600312.aspx) +- [Regular Expressions](/dotnet/standard/base-types/regular-expressions) diff --git a/docs/general/introduction-to-markup-compatibility.md b/docs/general/introduction-to-markup-compatibility.md index e9fcd5ac..fbbc0d69 100644 --- a/docs/general/introduction-to-markup-compatibility.md +++ b/docs/general/introduction-to-markup-compatibility.md @@ -11,7 +11,7 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 01/08/2025 ms.localizationpriority: high --- @@ -21,13 +21,13 @@ This topic introduces the markup compatibility features included in the Open XML ## Introduction -Suppose you have a Microsoft Word 2013 document that employs a feature introduced in Microsoft Office 2013. When you open that document in Microsoft Word 2010, an earlier version, what should happen? Ideally, you want the document to remain interoperable with Word 2010, even though Word 2010 will not understand the new feature. +Suppose you have a Microsoft Word 365 document that employs a feature introduced in Microsoft Office 365. When you open that document in Microsoft Word 2016, an earlier version, what should happen? Ideally, you want the document to remain interoperable with Word 2016, even though Word 2016 will not understand the new feature. -Consider also what should happen if you open that document in a hypothetical later version of Office. Here too, you want the document to work as expected. That is, you want the later version of Office to understand and support a feature employed in a document produced by Word 2013. +Consider also what should happen if you open that document in a hypothetical later version of Office. Here too, you want the document to work as expected. That is, you want the later version of Office to understand and support a feature employed in a document produced by Word 365. Open XML anticipates these scenarios. The Office Open XML File Formats specification describes facilities for achieving the above desired outcomes in [ECMA-376, Second Edition, Part 3 - Markup Compatibility and Extensibility](https://www.ecma-international.org/publications-and-standards/standards/ecma-376/). -The Open XML SDK supports markup compatibility in a way that makes it easy for you to achieve the above desired outcomes for and Office 2013 without having to necessarily become an expert in the specification details. +The Open XML SDK supports markup compatibility in a way that makes it easy for you to achieve the above desired outcomes for and Office 365 without having to necessarily become an expert in the specification details. ## What is markup compatibility? @@ -35,48 +35,44 @@ Open XML defines formats for word-processing, spreadsheet and presentation docum ## Markup compatibility in the Open XML file formats specification -Markup compatibility is discussed in [ECMA-376, Second Edition, Part 3 - Markup Compatibility and Extensibility](https://www.ecma-international.org/wp-content/uploads/ECMA-376-3_5th_edition_december_2015.zip), which is recommended reading to understand markup compatibility. The specification defines XML attributes to express compatibility rules, and XML elements to specify alternate content. For example, the **Ignorable** attribute specifies namespaces that can be ignored when they are not understood by the consuming application. Alternate-Content elements specify markup alternatives that can be chosen by an application at run time. For example, Word 2013 can choose only the markup alternative that it recognizes. The complete list of compatibility-rule attributes and alternate-content elements and their details can be found in the specification. +Markup compatibility is discussed in [ECMA-376, Second Edition, Part 3 - Markup Compatibility and Extensibility](https://www.ecma-international.org/wp-content/uploads/ECMA-376-3_5th_edition_december_2015.zip), which is recommended reading to understand markup compatibility. The specification defines XML attributes to express compatibility rules, and XML elements to specify alternate content. For example, the `Ignorable` attribute specifies namespaces that can be ignored when they are not understood by the consuming application. Alternate-Content elements specify markup alternatives that can be chosen by an application at run time. For example, Word 2013 can choose only the markup alternative that it recognizes. The complete list of compatibility-rule attributes and alternate-content elements and their details can be found in the specification. ## Open XML SDK support for markup compatibility The work that the Open XML SDK does for markup compatibility is detailed and subtle. However, the goal can be summarized as: using settings that you assign when you open a document, preprocess the document to: -1. Filter or remove any elements from namespaces that will not be understood (for example, Office 2013 document opened in Office 2010 context) +1. Filter or remove any elements from namespaces that will not be understood (for example, Office 365 document opened in Office 2016 context) 2. Process any markup compatibility elements and attributes as specified in the Open XML specification. The preprocessing performed is in accordance with ECMA-376, Second Edition: Part 3.13. -The Open XML SDK support for markup compatibility comes primarily in the form of two classes and in the manner in which content is preprocessed in accordance with ECMA-376, Second Edition. The two classes are **OpenSettings** and **MarkupCompatibilityProcessSettings**. Use the former to provide settings that apply to SDK behavior overall. Use the latter to supply one part of those settings, specifically those that apply to markup compatibility. +The Open XML SDK support for markup compatibility comes primarily in the form of two classes and in the manner in which content is preprocessed in accordance with ECMA-376, Second Edition. The two classes are `OpenSettings` and `MarkupCompatibilityProcessSettings`. Use the former to provide settings that apply to SDK behavior overall. Use the latter to supply one part of those settings, specifically those that apply to markup compatibility. ## Set the stage when you open -When you open a document using the Open XML SDK, you have the option of using an overload with a signature that accepts an instance of the **[OpenSettings](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.opensettings.aspx)** class as a parameter. You use the open settings class to provide certain important settings that govern the behavior of the SDK. One set of settings in particular, stored in the **[MarkupCompatibilityProcessSettings](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.opensettings.markupcompatibilityprocesssettings.aspx)** property, determines how markup compatibility elements and attributes are processed. You set the property to an instance of the **[MarkupCompatibilityProcessSettings](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.markupcompatibilityprocesssettings.aspx)** class prior to opening a document. +When you open a document using the Open XML SDK, you have the option of using an overload with a signature that accepts an instance of the class as a parameter. You use the open settings class to provide certain important settings that govern the behavior of the SDK. One set of settings in particular, stored in the property, determines how markup compatibility elements and attributes are processed. You set the property to an instance of the class prior to opening a document. The class has the following properties: -- **[ProcessMode](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.markupcompatibilityprocesssettings.processmode.aspx)** - Determines the parts that are preprocessed. +- - Determines the parts that are preprocessed. -- **[TargetFileFormatVersions](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.markupcompatibilityprocesssettings.targetfileformatversions.aspx)** - Specifies the context that applies to preprocessing. +- - Specifies the context that applies to preprocessing. By default, documents are not preprocessed. If however you do specify open settings and provide markup compatibility process settings, then the document is preprocessed in accordance with those settings. -The following code example demonstrates how to call the Open method with an instance of the open settings class as a parameter. Notice that the **ProcessMode** and **TargetFileFormatVersions** properties are initialized as part of the **MarkupCompatiblityProcessSettings** constructor. +The following code example demonstrates how to call the Open method with an instance of the open settings class as a parameter. Notice that the `ProcessMode` and `TargetFileFormatVersions` properties are initialized as part of the `MarkupCompatiblityProcessSettings` constructor. ```csharp // Create instance of OpenSettings OpenSettings openSettings = new OpenSettings(); // Add the MarkupCompatibilityProcessSettings - openSettings.MarkupCompatibilityProcessSettings = - new MarkupCompatibilityProcessSettings( - MarkupCompatibilityProcessMode.ProcessAllParts, + openSettings.MarkupCompatibilityProcessSettings = new MarkupCompatibilityProcessSettings( + MarkupCompatibilityProcessMode.ProcessAllParts, FileFormatVersions.Office2007); // Open the document with OpenSettings - using (WordprocessingDocument wordDocument = - WordprocessingDocument.Open(filename, - true, - openSettings)) + using (WordprocessingDocument wordDocument = WordprocessingDocument.Open(filename, true, openSettings)) { // ... more code here } @@ -86,24 +82,23 @@ The following code example demonstrates how to call the Open method with an inst During preprocessing, the Open XML SDK removes elements and attributes in the markup compatibility namespace, removing the contents of unselected alternate-content elements, and interpreting compatibility-rule attributes as appropriate. This work is guided by the process mode and target file format versions properties. -The **ProcessMode** property determines the parts to be preprocessed. The content in *those* parts is filtered to contain only elements that are understood by the application version indicated in the **TargetFileFormatVersions** property. +The `ProcessMode` property determines the parts to be preprocessed. The content in *those* parts is filtered to contain only elements that are understood by the application version indicated in the `TargetFileFormatVersions` property. > [!WARNING] > Preprocessing affects what gets saved. When you save a file, the only markup that is saved is that which remains after preprocessing. ## Understand process mode -The process mode specifies which document parts should be preprocessed. You set this property to a member of the **[MarkupCompatibilityProcessMode](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.markupcompatibilityprocessmode.aspx)** enumeration. The default value, **NoProcess**, indicates that no preprocessing is performed. Your application must be able to understand and handle any elements and attributes present in the document markup, including any of the elements and attributes in the Markup Compatibility namespace. +The process mode specifies which document parts should be preprocessed. You set this property to a member of the enumeration. The default value, `NoProcess`, indicates that no preprocessing is performed. Your application must be able to understand and handle any elements and attributes present in the document markup, including any of the elements and attributes in the Markup Compatibility namespace. -You might want to work on specific document parts while leaving the rest untouched. For example, you might want to ensure minimal modification to the file. In that case, specify **ProcessLoadedPartsOnly** for the process mode. With this setting, preprocessing and the associated filtering is only applied to the loaded document parts, not the entire document. +You might want to work on specific document parts while leaving the rest untouched. For example, you might want to ensure minimal modification to the file. In that case, specify `ProcessLoadedPartsOnly` for the process mode. With this setting, preprocessing and the associated filtering is only applied to the loaded document parts, not the entire document. -Finally, there is **ProcessAllParts**, which specifies what the name implies. When you choose this value, the entire document is preprocessed. +Finally, there is `ProcessAllParts`, which specifies what the name implies. When you choose this value, the entire document is preprocessed. ## Set the target file format version -The target file format versions property lets you choose to process markup compatibility content in either Office 2010 or Office 2013 context. Set the **TargetFileFormatVersions** property to a member of the **[FileFormatVersions](https://msdn.microsoft.com/library/office/documentformat.openxml.fileformatversions.aspx)** enumeration. +The target file format versions property lets you choose to process markup compatibility content in the context of a specific Office version, e.g. Office 365. Set the `TargetFileFormatVersions` property to a member of the enumeration. -The default value, **Office2010**, means the SDK will assume that namespaces defined in Office 2010 are understood, but not namespaces defined in Office 2013. Thus, during preprocessing, the SDK will ignore the namespaces defined in Office 2013 and choose the Office 2010 compatible alternate-content. +The default value, `Office2007`, means the SDK will assume that namespaces defined in Office 2007 are understood, but not namespaces defined in Office 2010 or later. Thus, during preprocessing, the SDK will ignore the namespaces defined in newer Office versions and choose the Office 2007 compatible alternate-content. -When you set the target file format versions property to **Office2013**, the Open XML SDK assumes that all of the namespaces defined in Office 2010 and Office 2013 are understood, does not ignore any content defined under Office 2013, and will choose -the Office 2013 compatible alternate-content. +When you set the target file format versions property to `Office2013`, the Open XML SDK assumes that all of the namespaces defined in Office 2010 and Office 2013 are understood, does not ignore any content defined under Office 2013, and will choose the Office 2013 compatible alternate-content. diff --git a/docs/general/overview.md b/docs/general/overview.md index 0aae015e..32a0e485 100644 --- a/docs/general/overview.md +++ b/docs/general/overview.md @@ -11,7 +11,7 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 01/03/2025 ms.localizationpriority: high --- @@ -19,31 +19,30 @@ ms.localizationpriority: high This section provides how-to topics for working with documents and packages using the Open XML SDK. - ## In this section - [Features in Open XML SDK](features.md) - [Introduction to markup compatibility](introduction-to-markup-compatibility.md) -- [Add a new document part that receives a relationship ID to a package](how-to-add-a-new-document-part-that-receives-a-relationship-id-to-a-package.md) +- [Add a new document part that receives a relationship ID to a package](how-to-add-a-new-document-part-that-receives-a-relationship-id-to-a-package.md) -- [Add a new document part to a package](how-to-add-a-new-document-part-to-a-package.md) +- [Add a new document part to a package](how-to-add-a-new-document-part-to-a-package.md) -- [Copy the contents of an Open XML package part to a document part in a different package](how-to-copy-the-contents-of-an-open-xml-package-part-to-a-document-part-in-a-dif.md) +- [Copy the contents of an Open XML package part to a document part in a different package](how-to-copy-the-contents-of-an-open-xml-package-part-to-a-document-part-in-a-dif.md) -- [Create a package](how-to-create-a-package.md) +- [Create a package](how-to-create-a-package.md) -- [Get the contents of a document part from a package](how-to-get-the-contents-of-a-document-part-from-a-package.md) +- [Get the contents of a document part from a package](how-to-get-the-contents-of-a-document-part-from-a-package.md) -- [Remove a document part from a package](how-to-remove-a-document-part-from-a-package.md) +- [Remove a document part from a package](how-to-remove-a-document-part-from-a-package.md) -- [Replace the theme part in a word processing document](how-to-replace-the-theme-part-in-a-word-processing-document.md) +- [Replace the theme part in a word processing document](how-to-replace-the-theme-part-in-a-word-processing-document.md) -- [Search and replace text in a document part](how-to-search-and-replace-text-in-a-document-part.md) +- [Search and replace text in a document part](how-to-search-and-replace-text-in-a-document-part.md) - [Diagnostic IDs](diagnosticids.md) -## Related sections +## Related sections -- [Getting started with the Open XML SDK for Office](../getting-started.md) +- [Getting started with the Open XML SDK for Office](../getting-started.md) diff --git a/docs/includes/iso-iec-29500-2-link.md b/docs/includes/iso-iec-29500-2-link.md new file mode 100644 index 00000000..ea311344 --- /dev/null +++ b/docs/includes/iso-iec-29500-2-link.md @@ -0,0 +1 @@ +[ISO/IEC 29500-2](https://www.iso.org/standard/77818.html) \ No newline at end of file diff --git a/docs/includes/iso-iec-29500-link.md b/docs/includes/iso-iec-29500-link.md new file mode 100644 index 00000000..bec1b3d5 --- /dev/null +++ b/docs/includes/iso-iec-29500-link.md @@ -0,0 +1 @@ +[ISO/IEC 29500](https://www.iso.org/standard/71691.html) \ No newline at end of file diff --git a/docs/includes/iso-iec-29500-version.md b/docs/includes/iso-iec-29500-version.md new file mode 100644 index 00000000..e9607094 --- /dev/null +++ b/docs/includes/iso-iec-29500-version.md @@ -0,0 +1 @@ +ISO/IEC 29500: 2016 \ No newline at end of file diff --git a/docs/includes/presentation/modern-comment-description.md b/docs/includes/presentation/modern-comment-description.md new file mode 100644 index 00000000..d3bb6e83 --- /dev/null +++ b/docs/includes/presentation/modern-comment-description.md @@ -0,0 +1,68 @@ +## The Structure of the Modern Comment Element + +The following XML element specifies a single comment. +It contains the text of the comment (`t`) and attributes referring to its author +(`authorId`), date time created (`created`), and comment id (`id`). + +```xml + + + + + + + Needs more cowbell + + + + +``` + +The following tables list the definitions of the possible child elements and attributes +of the `cm` (comment) element. For the complete definition see [MS-PPTX 2.16.3.3 CT_Comment](/openspecs/office_standards/ms-pptx/161bc2c9-98fc-46b7-852b-ba7ee77e2e54) + + +| Attribute | Definition | +|---|---| +| id | Specifies the ID of a comment or a comment reply. | +| authorId | Specifies the author ID of a comment or a comment reply. | +| status | Specifies the status of a comment or a comment reply. | +| created | Specifies the date time when the comment or comment reply is created. | +| startDate | Specifies start date of the comment. | +| dueDate | Specifies due date of the comment. | +| assignedTo | Specifies a list of authors to whom the comment is assigned. | +| complete | Specifies the completion percentage of the comment. | +| title | Specifies the title for a comment. | + +| Child Element | Definition | +|------------|---------------| +| pc:sldMkLst | Specifies a content moniker that identifies the slide to which the comment is anchored. | +| ac:deMkLst | Specifies a content moniker that identifies the drawing element to which the comment is anchored. | +| ac:txMkLst | Specifies a content moniker that identifies the text character range to which the comment is anchored. | +| unknownAnchor | Specifies an unknown anchor to which the comment is anchored. | +| pos | Specifies the position of the comment, relative to the top-left corner of the first object to which the comment is anchored. | +| replyLst | Specifies the list of replies to the comment. | +| txBody | Specifies the text of a comment or a comment reply. | +| extLst | Specifies a list of extensions for a comment or a comment reply. | + + + +The following XML schema example defines the members of the `cm` element in addition to the required and +optional attributes. + +```xml + + + + + + + + + + + + + + +``` \ No newline at end of file diff --git a/docs/includes/presentation/structure.md b/docs/includes/presentation/structure.md index a1d15f8a..7a16c732 100644 --- a/docs/includes/presentation/structure.md +++ b/docs/includes/presentation/structure.md @@ -1,13 +1,13 @@ ## Basic Presentation Document Structure -The basic document structure of a **PresentationML** document consists of a number of +The basic document structure of a `PresentationML` document consists of a number of parts, among which is the main part that contains the presentation -definition. The following text from the [ISO/IEC 29500](https://www.iso.org/standard/71691.html) specification -introduces the overall form of a **PresentationML** package. +definition. The following text from the [!include[ISO/IEC 29500 URL](../iso-iec-29500-link.md)] specification +introduces the overall form of a `PresentationML` package. -> The main part of a **PresentationML** package +> The main part of a `PresentationML` package > starts with a presentation root element. That element contains a -> presentation, which, in turn, refers to a **slide** list, a *slide master* list, a *notes +> presentation, which, in turn, refers to a *slide* list, a *slide master* list, a *notes > master* list, and a *handout master* list. The slide list refers to > all of the slides in the presentation; the slide master list refers to > the entire slide masters used in the presentation; the notes master @@ -23,17 +23,17 @@ introduces the overall form of a **PresentationML** package. > maintaining the presentation slide deck. A note is a reminder or piece > of text intended for the presenter or the audience. > -> Other features that a **PresentationML** +> Other features that a `PresentationML` > document can include the following: *animation*, *audio*, *video*, and > *transitions* between slides. > -> A **PresentationML** document is not stored +> A `PresentationML` document is not stored > as one large body in a single part. Instead, the elements that > implement certain groupings of functionality are stored in separate -> parts. For example, all comments in a document are stored in one -> comment part while each slide has its own part. +> parts. For example, all authors in a document are stored in one +> authors part while each slide has its own part. > -> © ISO/IEC29500: 2008. +> [!include[ISO/IEC 29500 version](../iso-iec-29500-version.md)] The following XML code example represents a presentation that contains two slides denoted by the IDs 267 and 256. @@ -65,13 +65,13 @@ two slides denoted by the IDs 267 and 256. Using the Open XML SDK, you can create document structure and content using strongly-typed classes that correspond to PresentationML -elements. You can find these classes in the [DocumentFormat.OpenXml.Presentation](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.aspx) +elements. You can find these classes in the namespace. The following table lists the class names of the classes that -correspond to the **sld**, **sldLayout**, **sldMaster**, and **notesMaster** elements. +correspond to the `sld`, `sldLayout`, `sldMaster`, and `notesMaster` elements. -| PresentationML Element | Open XML SDK Class | Description | +| **PresentationML Element** | **Open XML SDK Class** | **Description** | |---|---|---| -| sld | [Slide](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.slide.aspx) | Presentation Slide. It is the root element of SlidePart. | -| sldLayout | [SlideLayout](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.slidelayout.aspx) | Slide Layout. It is the root element of SlideLayoutPart. | -| sldMaster | [SlideMaster](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.slidemaster.aspx) | Slide Master. It is the root element of SlideMasterPart. | -| notesMaster | [NotesMaster](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.notesmaster.aspx) | Notes Master (or handoutMaster). It is the root element of NotesMasterPart. | \ No newline at end of file +| `` | | Presentation Slide. It is the root element of SlidePart. | +| `` | | Slide Layout. It is the root element of SlideLayoutPart. | +| `` | | Slide Master. It is the root element of SlideMasterPart. | +| `` | | Notes Master (or handoutMaster). It is the root element of NotesMasterPart. | \ No newline at end of file diff --git a/docs/includes/presentation/using-statement.md b/docs/includes/presentation/using-statement.md new file mode 100644 index 00000000..d2cc37e4 --- /dev/null +++ b/docs/includes/presentation/using-statement.md @@ -0,0 +1,5 @@ +With v3.0.0+ the method +has been removed in favor of relying on the [using statement](/dotnet/csharp/language-reference/statements/using). +This ensures that the method is automatically called +when the closing brace is reached. The block that follows the `using` statement establishes a scope for the +object that is created or named in the `using` statement, in this case diff --git a/docs/includes/spreadsheet/open-spreadsheet.md b/docs/includes/spreadsheet/open-spreadsheet.md new file mode 100644 index 00000000..a1c0db01 --- /dev/null +++ b/docs/includes/spreadsheet/open-spreadsheet.md @@ -0,0 +1,17 @@ +## Getting a SpreadsheetDocument Object + +In the Open XML SDK, the class represents an +Excel document package. To open and work with an Excel document, you +create an instance of the `SpreadsheetDocument` class from the document. +After you create the instance from the document, you can then obtain +access to the main workbook part that contains the worksheets. The text +in the document is represented in the package as XML using `SpreadsheetML` markup. + +To create the class instance from the document that you call one of the + methods. Several are provided, each +with a different signature. The sample code in this topic uses the @"DocumentFormat.OpenXml.Packaging.SpreadsheetDocument.Open*?text=Open(String, Boolean)" method with a +signature that requires two parameters. The first parameter takes a full +path string that represents the document that you want to open. The +second parameter is either `true` or `false` and represents whether you want the file to +be opened for editing. Any changes that you make to the document will +not be saved if this parameter is `false`. \ No newline at end of file diff --git a/docs/includes/spreadsheet/spreadsheet-object.md b/docs/includes/spreadsheet/spreadsheet-object.md new file mode 100644 index 00000000..d2c8a6d6 --- /dev/null +++ b/docs/includes/spreadsheet/spreadsheet-object.md @@ -0,0 +1,55 @@ +## The SpreadsheetDocument Object + +The basic document structure of a SpreadsheetML document consists of the + and elements, which reference the +worksheets in the . A separate XML file is created +for each . For example, the SpreadsheetML +for a workbook that has two worksheets name MySheet1 and MySheet2 is +located in the Workbook.xml file and is as follows. + +```xml + + + + + + + +``` + +The worksheet XML files contain one or more block level elements such as +. `sheetData` represents the cell table and contains +one or more elements. A `row` contains one or more elements. Each cell contains a element that represents the value +of the cell. For example, the SpreadsheetML for the first worksheet in a +workbook, that only has the value 100 in cell A1, is located in the +Sheet1.xml file and is as follows. + +```xml + + + + + + 100 + + + + +``` + +Using the Open XML SDK, you can create document structure and +content that uses strongly-typed classes that correspond to +SpreadsheetML elements. You can find these classes in the `DocumentFormat.OpenXML.Spreadsheet` namespace. The +following table lists the class names of the classes that correspond to +the `workbook`, `sheets`, `sheet`, `worksheet`, and `sheetData` elements. + +| **SpreadsheetML Element**|**Open XML SDK Class**|**Description** | +|--|--|--| +| ``||The root element for the main document part. | +| ``||The container for the block level structures such as sheet, fileVersion, and |others specified in the [!include[ISO/IEC 29500 URL](../iso-iec-29500-link.md)] specification. +| ``||A sheet that points to a sheet definition file. | +| ``||A sheet definition file that contains the sheet data. | +| ``||The cell table, grouped together by rows. | +| ``||A row in the cell table. | +| ``||A cell in a row. | +| ``||The value of a cell. | \ No newline at end of file diff --git a/docs/includes/spreadsheet/structure.md b/docs/includes/spreadsheet/structure.md index 3cdbdc31..7bb22036 100644 --- a/docs/includes/spreadsheet/structure.md +++ b/docs/includes/spreadsheet/structure.md @@ -1,10 +1,10 @@ ## Basic structure of a spreadsheetML document -The basic document structure of a **SpreadsheetML** document consists of the [Sheets](https://msdn.microsoft.com/library/office/documentformat.openxml.spreadsheet.sheets.aspx) and [Sheet](https://msdn.microsoft.com/library/office/documentformat.openxml.spreadsheet.sheet.aspx) elements, which reference the worksheets in the workbook. A separate XML file is created for each worksheet. For example, the **SpreadsheetML** for a [Workbook](https://msdn.microsoft.com/library/office/documentformat.openxml.spreadsheet.workbook.aspx) that has two worksheets name MySheet1 and MySheet2 is located in the Workbook.xml file and is shown in the following code example. +The basic document structure of a `SpreadsheetML` document consists of the and elements, which reference the worksheets in the workbook. A separate XML file is created for each worksheet. For example, the `SpreadsheetML` for a that has two worksheets name MySheet1 and MySheet2 is located in the Workbook.xml file and is shown in the following code example. ```xml - + @@ -13,16 +13,16 @@ The basic document structure of a **SpreadsheetML** document consists of the [Sh ``` The worksheet XML files contain one or more block level elements such as -[sheetData](https://msdn.microsoft.com/library/office/documentformat.openxml.spreadsheet.sheetdata.aspx) represents the cell table and contains -one or more [Row](https://msdn.microsoft.com/library/office/documentformat.openxml.spreadsheet.row.aspx) elements. A **row** contains one or more [Cell](https://msdn.microsoft.com/library/office/documentformat.openxml.spreadsheet.cell.aspx) elements. Each cell contains a [CellValue](https://msdn.microsoft.com/library/office/documentformat.openxml.spreadsheet.cellvalue.aspx) element that represents the value -of the cell. For example, the **SpreadsheetML** + represents the cell table and contains +one or more elements. A `row` contains one or more elements. Each cell contains a element that represents the value +of the cell. For example, the `SpreadsheetML` for the first worksheet in a workbook, that only has the value 100 in cell A1, is located in the Sheet1.xml file and is shown in the following code example. ```xml - + @@ -34,18 +34,18 @@ code example. ``` Using the Open XML SDK, you can create document structure and -content that uses strongly-typed classes that correspond to **SpreadsheetML** elements. You can find these -classes in the **DocumentFormat.OpenXML.Spreadsheet** namespace. The +content that uses strongly-typed classes that correspond to `SpreadsheetML` elements. You can find these +classes in the `DocumentFormat.OpenXML.Spreadsheet` namespace. The following table lists the class names of the classes that correspond to -the **workbook**, **sheets**, **sheet**, **worksheet**, and **sheetData** elements. +the `workbook`, `sheets`, `sheet`, `worksheet`, and `sheetData` elements. | **SpreadsheetML Element** | **Open XML SDK Class** | **Description** | |:---|:---|:---| -| workbook | DocumentFormat.OpenXML.Spreadsheet.Workbook | The root element for the main document part. | -| sheets | DocumentFormat.OpenXML.Spreadsheet.Sheets | The container for the block level structures such as sheet, fileVersion, and others specified in the [ISO/IEC 29500](https://www.iso.org/standard/71691.html) specification. | -| sheet | DocumentFormat.OpenXml.Spreadsheet.Sheet | A sheet that points to a sheet definition file. | -| worksheet | DocumentFormat.OpenXML.Spreadsheet. Worksheet | A sheet definition file that contains the sheet data. | -| sheetData | DocumentFormat.OpenXML.Spreadsheet.SheetData | The cell table, grouped together by rows. | -| row | DocumentFormat.OpenXml.Spreadsheet.Row | A row in the cell table. | -| c | DocumentFormat.OpenXml.Spreadsheet.Cell | A cell in a row. | -| v | DocumentFormat.OpenXml.Spreadsheet.CellValue | The value of a cell. | +| `` | DocumentFormat.OpenXML.Spreadsheet.Workbook | The root element for the main document part. | +| `` | DocumentFormat.OpenXML.Spreadsheet.Sheets | The container for the block level structures such as sheet, fileVersion, and others specified in the [!include[ISO/IEC 29500 URL](../iso-iec-29500-link.md)] specification. | +| `` | DocumentFormat.OpenXml.Spreadsheet.Sheet | A sheet that points to a sheet definition file. | +| `` | DocumentFormat.OpenXML.Spreadsheet. Worksheet | A sheet definition file that contains the sheet data. | +| `` | DocumentFormat.OpenXML.Spreadsheet.SheetData | The cell table, grouped together by rows. | +| `` | DocumentFormat.OpenXml.Spreadsheet.Row | A row in the cell table. | +| `` | DocumentFormat.OpenXml.Spreadsheet.Cell | A cell in a row. | +| `` | DocumentFormat.OpenXml.Spreadsheet.CellValue | The value of a cell. | diff --git a/docs/includes/word/packages-and-document-parts.md b/docs/includes/word/packages-and-document-parts.md new file mode 100644 index 00000000..4c1dbf9b --- /dev/null +++ b/docs/includes/word/packages-and-document-parts.md @@ -0,0 +1,13 @@ +## Packages and Document Parts + +An Open XML document is stored as a package, whose format is defined by +[!include[ISO/IEC 29500 URL](../iso-iec-29500-link.md)]. The +package can have multiple parts with relationships between them. The +relationship between parts controls the category of the document. A +document can be defined as a word-processing document if its +package-relationship item contains a relationship to a main document +part. If its package-relationship item contains a relationship to a +presentation part it can be defined as a presentation document. If its +package-relationship item contains a relationship to a workbook part, it +is defined as a spreadsheet document. In this how-to topic, you will use +a word-processing document package. \ No newline at end of file diff --git a/docs/includes/word/structure.md b/docs/includes/word/structure.md index 0254f652..56f1614a 100644 --- a/docs/includes/word/structure.md +++ b/docs/includes/word/structure.md @@ -1,9 +1,9 @@ ## Structure of a WordProcessingML Document -The basic document structure of a **WordProcessingML** document consists of the **document** and **body** elements, followed by one or more block level elements such as **p**, which represents a paragraph. A paragraph contains one or more **r** elements. The **r** stands for run, which is a region of text with a common set of properties, such as formatting. A run contains one or more **t** elements. The **t** element contains a range of text. The following code example shows the **WordprocessingML** markup for a document that contains the text "Example text." +The basic document structure of a `WordProcessingML` document consists of the `document` and `body` elements, followed by one or more block level elements such as `p`, which represents a paragraph. A paragraph contains one or more `r` elements. The `r` stands for run, which is a region of text with a common set of properties, such as formatting. A run contains one or more `t` elements. The `t` element contains a range of text. The following code example shows the `WordprocessingML` markup for a document that contains the text "Example text." ```xml - + @@ -14,14 +14,14 @@ The basic document structure of a **WordProcessingML** document consists of the ``` -Using the Open XML SDK, you can create document structure and content using strongly-typed classes that correspond to **WordprocessingML** elements. You will find these classes in the [DocumentFormat.OpenXml.Wordprocessing](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.aspx) namespace. The following table lists the class names of the classes that correspond to the **document**, **body**, **p**, **r**, and **t** elements. +Using the Open XML SDK, you can create document structure and content using strongly-typed classes that correspond to `WordprocessingML` elements. You will find these classes in the namespace. The following table lists the class names of the classes that correspond to the `document`, `body`, `p`, `r`, and `t` elements. -| WordprocessingML Element | Open XML SDK Class | Description | +| **WordprocessingML Element** | **Open XML SDK Class** | **Description** | |---|---|---| -| document | [Document](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.document.aspx) | The root element for the main document part. | -| body | [Body](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.body.aspx) | The container for the block level structures such as paragraphs, tables, annotations and others specified in the [ISO/IEC 29500](https://www.iso.org/standard/71691.html) specification. | -| p | [Paragraph](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.paragraph.aspx) | A paragraph. | -| r | [Run](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.run.aspx) | A run. | -| t | [Text](https://msdn.microsoft.com/library/office/documentformat.openxml.wordprocessing.text.aspx) | A range of text. | +| `` | | The root element for the main document part. | +| `` | | The container for the block level structures such as paragraphs, tables, annotations and others specified in the [!include[ISO/IEC 29500 URL](../iso-iec-29500-link.md)] specification. | +| `

` | | A paragraph. | +| `` | | A run. | +| `` | | A range of text. | For more information about the overall structure of the parts and elements of a WordprocessingML document, see [Structure of a WordprocessingML document](../../word/structure-of-a-wordprocessingml-document.md). \ No newline at end of file diff --git a/docs/includes/word/using-statement.md b/docs/includes/word/using-statement.md new file mode 100644 index 00000000..68e0d9f4 --- /dev/null +++ b/docs/includes/word/using-statement.md @@ -0,0 +1,10 @@ +With v3.0.0+ the method +has been removed in favor of relying on the [using statement](/dotnet/csharp/language-reference/statements/using). +It ensures that the method is automatically called +when the closing brace is reached. The block that follows the using +statement establishes a scope for the object that is created or named in +the using statement. Because the class in the Open XML SDK +automatically saves and closes the object as part of its implementation, and because + is automatically called when you +exit the block, you do not have to explicitly call or + as long as you use a `using` statement. \ No newline at end of file diff --git a/docs/media/custom-property-menu.png b/docs/media/custom-property-menu.png new file mode 100644 index 00000000..8cdc0edc Binary files /dev/null and b/docs/media/custom-property-menu.png differ diff --git a/docs/migration/migrate-v2-to-v3.md b/docs/migration/migrate-v2-to-v3.md index 4b42b2fb..199c92ef 100644 --- a/docs/migration/migrate-v2-to-v3.md +++ b/docs/migration/migrate-v2-to-v3.md @@ -93,7 +93,7 @@ if (theCell.DataType.Value == CellValues.SharedString) ### OpenXmlElementList is now a struct -[OpenXmlElementList](/dotnet/api/documentformat.openxml.openxmlelementlist) is now a struct. It still implements `IEnumerable` in addition to `IReadOnlyList` where available. + is now a struct. It still implements `IEnumerable` in addition to `IReadOnlyList` where available. **Action needed**: Because this is a struct, code patterns that may have a `null` result will now be a `OpenXmlElementList?` instead. Null checks will be flagged by the compiler and the value itself will need to be unwrapped, such as: @@ -117,7 +117,7 @@ This type is used to enumerate pairs within a part and caused many unnecessary a ### OpenXmlPartReader no longer knows about all parts -In previous versions, [OpenXmlPartReader](/dotnet/api/documentformat.openxml.openxmlpartreader) knew about about all strongly typed part. In order to reduce coupling required for better AOT scenarios, we now have typed readers for known packages: `WordprocessingDocumentPartReader`, `SpreadsheetDocumentPartReader`, and `PresentationDocumentPartReader`. +In previous versions, knew about about all strongly typed part. In order to reduce coupling required for better AOT scenarios, we now have typed readers for known packages: `WordprocessingDocumentPartReader`, `SpreadsheetDocumentPartReader`, and `PresentationDocumentPartReader`. **Action needed**: Replace usage of `OpenXmlPartReader` with document specific readers if needed. If creating a part reader from a known package, please use the constructors that take an existing `OpenXmlPart` which will then create the expected strongly typed parts. diff --git a/docs/open-xml-sdk.md b/docs/open-xml-sdk.md index aa3a67de..c6e28acd 100644 --- a/docs/open-xml-sdk.md +++ b/docs/open-xml-sdk.md @@ -29,7 +29,7 @@ API and provides strongly-typed classes to manipulate documents that adhere to the Office Open XML File Formats specification. The Office Open XML File Formats specification is an open, international, [ECMA-376, 5th Edition](https://www.ecma-international.org/publications-and-standards/standards/ecma-376/) -and [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) +and [!include[ISO/IEC 29500 URL](./includes/iso-iec-29500-link.md)] standard. The Open XML file formats are useful for developers because they are an open standard and are based on well-known technologies: ZIP and XML. @@ -40,7 +40,7 @@ The Open XML SDK encapsulates many common tasks that developers perform on Open XML packages, so that you can perform complex operations with just a few lines of code. -Portions of ISO/IEC 29500:20081 are referenced in the SDK. +Portions of [!include[ISO/IEC 29500 version](./includes/iso-iec-29500-version.md)]1 are referenced in the SDK. [!include[Add-ins note](./includes/addinsnote.md)] @@ -65,8 +65,8 @@ Portions of ISO/IEC 29500:20081 are referenced in the SDK. - [Open XML SDK for Microsoft Office](https://www.nuget.org/packages/DocumentFormat.OpenXml) - [Microsoft Office Developer Center](https://developer.microsoft.com/office/docs) - [Samples on GitHub](https://github.com/OfficeDev) -- [Open XML SDK copyright notice](https://msdn.microsoft.com/library/6165f4ad-2e4d-4852-921a-087782af364d(Office.15).aspx) +- [Open XML SDK copyright notice](/previous-versions/office/bb509417(v=office.15)) - [Accessibility features in the Microsoft Office System](https://www.microsoft.com/accessibility/) -- [Document conventions in Office Developer documentation](https://msdn.microsoft.com/office/aa905365.aspx) +- [Document conventions in Office Developer documentation](/previous-versions/office/dn602610(v=office.15)) -1© ISO/IEC2900:2008. This material is reproduced from ISO/IEC 29500:2008 with permission of the American National Standards Institute (ANSI) on behalf of ISO. +1© [!include[ISO/IEC 29500 version](./includes/iso-iec-29500-version.md)]. This material is reproduced from [!include[ISO/IEC 29500 version](./includes/iso-iec-29500-version.md)] with permission of the American National Standards Institute (ANSI) on behalf of ISO. diff --git a/docs/presentation/how-to-add-a-comment-to-a-slide-in-a-presentation.md b/docs/presentation/how-to-add-a-comment-to-a-slide-in-a-presentation.md index 0fcef1de..5a414143 100644 --- a/docs/presentation/how-to-add-a-comment-to-a-slide-in-a-presentation.md +++ b/docs/presentation/how-to-add-a-comment-to-a-slide-in-a-presentation.md @@ -11,7 +11,7 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 01/02/2025 ms.localizationpriority: medium --- @@ -21,77 +21,91 @@ This topic shows how to use the classes in the Open XML SDK for Office to add a comment to the first slide in a presentation programmatically. +> [!NOTE] +> This sample is for PowerPoint modern comments. For classic comments view +> the [archived sample on GitHub](https://github.com/OfficeDev/open-xml-docs/blob/7002d692ab4abc629d617ef6a0214fc2bf2910c8/docs/how-to-add-a-comment-to-a-slide-in-a-presentation.md). + [!include[Structure](../includes/presentation/structure.md)] -## The Structure of the Comment Element - -A comment is a text note attached to a slide, with the primary purpose -of enabling readers of a presentation to provide feedback to the -presentation author. Each comment contains an unformatted text string -and information about its author, and is attached to a particular -location on a slide. Comments can be visible while editing the -presentation, but do not appear when a slide show is given. The -displaying application decides when to display comments and determines -their visual appearance. - -The following XML element specifies a single comment attached to a -slide. It contains the text of the comment (**text**), its position on the slide (**pos**), and attributes referring to its author -(**authorId**), date and time (**dt**), and comment index (**idx**). - -```xml - - - Add diagram to clarify. - -``` - -The following table contains the definitions of the members and -attributes of the **cm** (comment) element. - -| Member/Attribute | Definition | -|---|---| -| authorId | Refers to the ID of an author in the comment author list for the document. | -| dt | The date and time this comment was last modified. | -| idx | An identifier for this comment that is unique within a list of all comments by this author in this document. An author's first comment in a document has index 1. | -| pos | The positioning information for the placement of a comment on a slide surface. | -| text | Comment text. | -| extLst | Specifies the extension list with modification ability within which all future extensions of element type ext are defined. The extension list along with corresponding future extensions is used to extend the storage capabilities of the PresentationML framework. This allows for various new kinds of data to be stored natively within the framework. | - - -The following XML schema code example defines the members of the **cm** element in addition to the required and -optional attributes. - -```xml - - - - - - - - - - -``` +[!include[description of a comment](../includes/presentation/modern-comment-description.md)] -## Sample Code +## How the Sample Code Works + +The sample code opens the presentation document in the using statement. Then it instantiates the CommentAuthorsPart, and verifies that there is an existing comment authors part. If there is not, it adds one. + +### [C#](#tab/cs-1) +[!code-csharp[](../../samples/presentation/add_comment/cs/Program.cs#snippet1)] + +### [Visual Basic](#tab/vb-1) +[!code-vb[](../../samples/presentation/add_comment/vb/Program.vb#snippet1)] +*** + +The code determines whether there is an existing PowerPoint author part in the presentation part; if not, it adds one, then checks if there is an authors list +and adds one if it is missing. It also verifies that the author that is passed in is on the list of existing authors; if so, it assigns the existing author ID. If not, it adds a new author to the list of authors and assigns an author ID and the parameter values. + +### [C#](#tab/cs-2) +[!code-csharp[](../../samples/presentation/add_comment/cs/Program.cs#snippet2)] + +### [Visual Basic](#tab/vb-2) +[!code-vb[](../../samples/presentation/add_comment/vb/Program.vb#snippet2)] +*** + +Next the code determines if there is a slide id and returns if one does not exist + +### [C#](#tab/cs-3) +[!code-csharp[](../../samples/presentation/add_comment/cs/Program.cs#snippet3)] -The following code example shows how to add comments to a -presentation document. To run the program, you can pass in the arguments: +### [Visual Basic](#tab/vb-3) +[!code-vb[](../../samples/presentation/add_comment/vb/Program.vb#snippet3)] +*** + +In the segment below, the code gets the relationship ID. If it exists, it is used to find the slide part +otherwise the first slide in the slide parts enumerable is taken. Then it verifies that there is +a PowerPoint comments part for the slide and if not adds one. + +### [C#](#tab/cs-4) +[!code-csharp[](../../samples/presentation/add_comment/cs/Program.cs#snippet4)] + +### [Visual Basic](#tab/vb-4) +[!code-vb[](../../samples/presentation/add_comment/vb/Program.vb#snippet4)] +*** + +Below the code creates a new modern comment then adds a comment list to the PowerPoint comment part +if one does not exist and adds the comment to that comment list. + +### [C#](#tab/cs-5) +[!code-csharp[](../../samples/presentation/add_comment/cs/Program.cs#snippet5)] + +### [Visual Basic](#tab/vb-5) +[!code-vb[](../../samples/presentation/add_comment/vb/Program.vb#snippet5)] +*** + +With modern comments the slide needs to have the correct extension list and extension. +The following code determines if the slide already has a SlideExtensionList and +SlideExtension and adds them to the slide if they are not present. + +### [C#](#tab/cs-6) +[!code-csharp[](../../samples/presentation/add_comment/cs/Program.cs#snippet6)] + +### [Visual Basic](#tab/vb-6) +[!code-vb[](../../samples/presentation/add_comment/vb/Program.vb#snippet6)] +*** + +## Sample Code -```dotnetcli -dotnet run -- [filePath] [initials] [name] [test ...] -``` +Following is the complete code sample showing how to add a new comment with +a new or existing author to a slide with or without existing comments. > [!NOTE] > To get the exact author name and initials, open the presentation file and click the **File** menu item, and then click **Options**. The **PowerPointOptions** window opens and the content of the **General** tab is displayed. The author name and initials must match the **User name** and **Initials** in this tab. ### [C#](#tab/cs) -[!code-csharp[](../../samples/presentation/add_comment/cs/Program.cs)] +[!code-csharp[](../../samples/presentation/add_comment/cs/Program.cs#snippet0)] ### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/presentation/add_comment/vb/Program.vb)] +[!code-vb[](../../samples/presentation/add_comment/vb/Program.vb#snippet0)] +*** ## See also diff --git a/docs/presentation/how-to-add-a-video-to-a-slide-in-a-presentation.md b/docs/presentation/how-to-add-a-video-to-a-slide-in-a-presentation.md new file mode 100644 index 00000000..8ea4ea4b --- /dev/null +++ b/docs/presentation/how-to-add-a-video-to-a-slide-in-a-presentation.md @@ -0,0 +1,138 @@ +--- + +api_name: +- Microsoft.Office.DocumentFormat.OpenXML.Packaging +api_type: +- schema +ms.assetid: 536c94b5-dd25-4173-ad6a-b72b95dd7f31 +title: 'How to: Add a video to a slide in a presentation' +ms.suite: office + +ms.author: o365devx +author: o365devx +ms.topic: conceptual +ms.date: 04/03/2025 +ms.localizationpriority: medium +--- + +# Add a video to a slide in a presentation + +This topic shows how to use the classes in the Open XML SDK for +Office to add a video to the first slide in a presentation +programmatically. + +## Getting a Presentation Object + +In the Open XML SDK, the class represents a +presentation document package. To work with a presentation document, +first create an instance of the **PresentationDocument** class, and then work with +that instance. To create the class instance from the document call the + method that uses a file path, and a +Boolean value as the second parameter to specify whether a document is +editable. To open a document for read/write, specify the value `true` for this parameter as shown in the following +`using` statement. In this code, the file +parameter is a string that represents the path for the file from which +you want to open the document. + +### [C#](#tab/cs-1) +[!code-csharp[](../../samples/presentation/add_video/cs/Program.cs#snippet1)] + +### [Visual Basic](#tab/vb-1) +[!code-vb[](../../samples/presentation/add_video/vb/Program.vb#snippet1)] +*** + + +[!include[Using Statement](../includes/presentation/using-statement.md)] `ppt`. + + +## The Structure of the Video From File + +The PresentationML document consists of a number of parts, among which is the Picture (``) element. + +The following text from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification introduces the overall form of a `PresentationML` package. + +Video File (``) specifies the presence of a video file. It is defined within the non-visual properties of an object. The video shall be attached to an object as this is how it is represented within the document. The actual playing of the video however is done within the timing node list that is specified under the timing element. + +Consider the following `Picture` object that has a video attached to it. + +```xml + + + + + + + + + + + + + +``` + +In the above example, we see that there is a single videoFile element attached to this picture. This picture is placed within the document just as a normal picture or shape would be. The id of this picture, namely 7 in this case, is used to refer to this videoFile element from within the timing node list. The Linked relationship id is used to retrieve the actual video file for playback purposes. + +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] + +The following XML Schema fragment defines the contents of videoFile. + +```xml + + + + + + +``` + +## How the Sample Code Works + +After opening the presentation file for read/write access in the `using` statement, the code gets the presentation +part from the presentation document. Then it gets the relationship ID of +the last slide, and gets the slide part from the relationship ID. + + +### [C#](#tab/cs-2) +[!code-csharp[](../../samples/presentation/add_video/cs/Program.cs#snippet2)] + +### [Visual Basic](#tab/vb-2) +[!code-vb[](../../samples/presentation/add_video/vb/Program.vb#snippet2)] +*** + +The code first creates a media data part for the video file to be added. With the video file stream open, it feeds the media data part object. Next, video and media relationship references are added to the slide using the provided embedId for future reference to the video file and mediaEmbedId for media reference. + +An image part is then added with a sample picture to be used as a placeholder for the video. A picture object is created with various elements, such as Non-Visual Drawing Properties (``), which specify non-visual canvas properties. This allows for additional information that does not affect the appearance of the picture to be stored. The `` element, explained above, is also included. The HyperLinkOnClick (``) element specifies the on-click hyperlink information to be applied to a run of text or image. When the hyperlink text or image is clicked, the link is fetched. Non-Visual Picture Drawing Properties (``) specify the non-visual properties for the picture canvas. For a detailed explanation of the elements used, please refer to [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] + +### [C#](#tab/cs-3) +[!code-csharp[](../../samples/presentation/add_video/cs/Program.cs#snippet3)] + +### [Visual Basic](#tab/vb-3) +[!code-vb[](../../samples/presentation/add_video/vb/Program.vb#snippet3)] +*** + +Next Media(CT_Media) element is created with use of previously referenced mediaEmbedId(Embedded Picture Reference). The Blip element is also added; this element specifies the existence of an image (binary large image or picture) and contains a reference to the image data. Blip's Embed attribute is used to specify a placeholder image in the Image Part created previously. + +### [C#](#tab/cs-4) +[!code-csharp[](../../samples/presentation/add_video/cs/Program.cs#snippet4)] + +### [Visual Basic](#tab/vb-4) +[!code-vb[](../../samples/presentation/add_video/vb/Program.vb#snippet4)] +*** + +All other elements such Offset(``), Stretch(``), FillRectangle(``), are appended to the ShapeProperties(``) and ShapeProperties are appended to the Picture element(``). Finally the picture element that incudes video is added to the ShapeTree(``) of the slide. + +Following is the complete sample code that you can use to add video to the slide. + +## Sample Code + +### [C#](#tab/cs) +[!code-csharp[](../../samples/presentation/add_video/cs/Program.cs#snippet0)] + +### [Visual Basic](#tab/vb) +[!code-vb[](../../samples/presentation/add_video/vb/Program.vb#snippet0)] +*** + +## See also + +- [Open XML SDK class library reference](/office/open-xml/open-xml-sdk) diff --git a/docs/presentation/how-to-add-an-audio-to-a-slide-in-a-presentation.md b/docs/presentation/how-to-add-an-audio-to-a-slide-in-a-presentation.md new file mode 100644 index 00000000..03daef46 --- /dev/null +++ b/docs/presentation/how-to-add-an-audio-to-a-slide-in-a-presentation.md @@ -0,0 +1,133 @@ +--- + +api_name: +- Microsoft.Office.DocumentFormat.OpenXML.Packaging +api_type: +- schema +ms.assetid: 0265732e-d81a-4654-b0ba-d9d87e544f7c +title: 'How to: Add an audio file to a slide in a presentation' +ms.suite: office + +ms.author: o365devx +author: o365devx +ms.topic: conceptual +ms.date: 03/31/2025 +ms.localizationpriority: medium +--- + +# Add an audio file to a slide in a presentation + +This topic shows how to use the classes in the Open XML SDK for +Office to add an audio file to the last slide in a presentation +programmatically. + +## Getting a Presentation Object + +In the Open XML SDK, the class represents a presentation document package. To work with a presentation document, +first create an instance of the `PresentationDocument` class, and then work with +that instance. To create the class instance from the document call the method that uses a file path, and a +Boolean value as the second parameter to specify whether a document is editable. To open a document for read/write, specify the value `true` for this parameter as shown in the following +`using` statement. In this code, the file parameter is a string that represents the path for the file from which you want to open the document. + +### [C#](#tab/cs-1) +[!code-csharp[](../../samples/presentation/add_audio/cs/Program.cs#snippet1)] + +### [Visual Basic](#tab/vb-1) +[!code-vb[](../../samples/presentation/add_audio/vb/Program.vb#snippet1)] +*** + + +[!include[Using Statement](../includes/presentation/using-statement.md)] `ppt`. + + +## The Structure of the Audio From File + +The PresentationML document consists of a number of parts, among which is the Picture (``) element. + +The following text from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification introduces the overall form of a `PresentationML` package. + +Audio File (``) specifies the presence of an audio file. This element is specified within the non-visual properties of an object. The audio shall be attached to an object as this is how it is represented within the document. The actual playing of the audio however is done within the timing node list that is specified under the timing element. + +Consider the following ``Picture`` object that has an audio file attached to it. + +```xml + + + + + + + + + + + + + +``` + +In the above example, we see that there is a single audioFile element attached to this picture. This picture is placed within the document just as a normal picture or shape would be. The id of this picture, namely 7 in this case, is used to refer to this audioFile element from within the timing node list. The Linked relationship id is used to retrieve the actual audio file for playback purposes. + +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] + +The following XML Schema fragment defines the contents of audioFile. + +```xml + + + + + + +``` + +## How the Sample Code Works + +After opening the presentation file for read/write access in the `using` statement, the code gets the presentation +part from the presentation document. Then it gets the relationship ID of +the last slide, and gets the slide part from the relationship ID. + + +### [C#](#tab/cs-2) +[!code-csharp[](../../samples/presentation/add_audio/cs/Program.cs#snippet2)] + +### [Visual Basic](#tab/vb-2) +[!code-vb[](../../samples/presentation/add_audio/vb/Program.vb#snippet2)] +*** + +The code first creates a media data part for the audio file to be added. With the audio file stream open, it feeds the media data part object. Next, audio and media relationship references are added to the slide using the provided embedId for future reference to the audio file and mediaEmbedId for media reference. + +An image part is then added with a sample picture to be used as a placeholder for the audio. A picture object is created with various elements, such as Non-Visual Drawing Properties (``), which specify non-visual canvas properties. This allows for additional information that does not affect the appearance of the picture to be stored. The `` element, explained above, is also included. The HyperLinkOnClick (``) element specifies the on-click hyperlink information to be applied to a run of text or image. When the hyperlink text or image is clicked, the link is fetched. Non-Visual Picture Drawing Properties (``) specify the non-visual properties for the picture canvas. For a detailed explanation of the elements used, please refer to [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] + +### [C#](#tab/cs-3) +[!code-csharp[](../../samples/presentation/add_audio/cs/Program.cs#snippet3)] + +### [Visual Basic](#tab/vb-3) +[!code-vb[](../../samples/presentation/add_audio/vb/Program.vb#snippet3)] +*** + +Next the Media(CT_Media) element is created with use of the previously referenced mediaEmbedId(Embedded Picture Reference). The Blip element is also added; this element specifies the existence of an image (binary large image or picture) and contains a reference to the image data. Blip's Embed attribute is used to specify an placeholder image in the Image Part created previously. + +### [C#](#tab/cs-4) +[!code-csharp[](../../samples/presentation/add_audio/cs/Program.cs#snippet4)] + +### [Visual Basic](#tab/vb-4) +[!code-vb[](../../samples/presentation/add_audio/vb/Program.vb#snippet4)] +*** + +All other elements such as Offset(``), Stretch(``), fillRectangle(``), are appended to the ShapeProperties(``) and ShapeProperties are appended to the Picture element(``). Finally the picture element that includes audio is added to the ShapeTree(``) of the slide. + +Following is the complete sample code that you can use to add audio to the slide. + +## Sample Code + +### [C#](#tab/cs) +[!code-csharp[](../../samples/presentation/add_audio/cs/Program.cs#snippet0)] + +### [Visual Basic](#tab/vb) +[!code-vb[](../../samples/presentation/add_audio/vb/Program.vb#snippet0)] +*** + +## See also + +- [Open XML SDK class library reference](/office/open-xml/open-xml-sdk) diff --git a/docs/presentation/how-to-add-transitions-between-slides-in-a-presentation.md b/docs/presentation/how-to-add-transitions-between-slides-in-a-presentation.md new file mode 100644 index 00000000..2f230bae --- /dev/null +++ b/docs/presentation/how-to-add-transitions-between-slides-in-a-presentation.md @@ -0,0 +1,133 @@ +--- + +api_name: +- Microsoft.Office.DocumentFormat.OpenXML.Packaging +api_type: +- schema +ms.assetid: 5471f369-ad02-41c3-a5d3-ebaf618d185a +title: 'How to: Add transitions between slides in a presentation' +ms.suite: office + +ms.author: o365devx +author: o365devx +ms.topic: conceptual +ms.date: 04/03/2025 +ms.localizationpriority: medium +--- + +# Add Transitions between slides in a presentation + +This topic shows how to use the classes in the Open XML SDK to +add transition between all slides in a presentation programmatically. + +## Getting a Presentation Object + +In the Open XML SDK, the class represents a +presentation document package. To work with a presentation document, +first create an instance of the `PresentationDocument` class, and then work with +that instance. To create the class instance from the document, call the + method, that uses a file path, and a +Boolean value as the second parameter to specify whether a document is +editable. To open a document for read/write, specify the value `true` for this parameter as shown in the following +`using` statement. In this code, the file parameter, is a string that represents the path for the file from which you want to open the document. + +### [C#](#tab/cs-1) +[!code-csharp[](../../samples/presentation/add_transition/cs/Program.cs#snippet1)] + +### [Visual Basic](#tab/vb-1) +[!code-vb[](../../samples/presentation/add_transition/vb/Program.vb#snippet1)] +*** + +[!include[Using Statement](../includes/presentation/using-statement.md)] `ppt`. + +## The Structure of the Transition + +Transition element `` specifies the kind of slide transition that should be used to transition to the current slide from the +previous slide. That is, the transition information is stored on the slide that appears after the transition is +complete. + +The following table lists the attributes of the Transition along +with the description of each. + +| Attribute | Description | +|---|---| +| advClick (Advance on Click) | Specifies whether a mouse click advances the slide or not. If this attribute is not specified then a value of true is assumed. | +| advTm (Advance after time) | Specifies the time, in milliseconds, after which the transition should start. This setting can be used in conjunction with the advClick attribute. If this attribute is not specified then it is assumed that no auto-advance occurs. | +| spd (Transition Speed) |Specifies the transition speed that is to be used when transitioning from the current slide to the next. | + +[*Example*: Consider the following example + +```xml + + + +``` +In the above example, the transition speed `` is set to slow (available options: slow, med, fast). Advance on Click `` is set to true, and Advance after time `` is set to 3000 milliseconds. The Random Bar child element `` describes the randomBar slide transition effect, which uses a set of randomly placed horizontal `` or vertical `` bars on the slide that continue to be added until the new slide is fully shown. *end example*] + +A full list of Transition's child elements can be viewed here: + +## The Structure of the Alternate Content + +Office Open XML defines a mechanism for the storage of content that is not defined by the ISO/IEC 29500 Office Open XML specification, such as extensions developed by future software applications that leverage the Office Open XML formats. This mechanism allows for the storage of a series of alternative representations of content, from which the consuming application can use the first alternative whose requirements are met. + +Consider an application that creates a new transition object intended to specify the duration of the transition. This functionality is not defined in the Office Open XML specification. Using an AlternateContent block as follows allows specifying the duration `` in milliseconds. + +[*Example*: +```xml + + + + + + + + + + + + +``` + +The Choice element in the above example requires the attribute to specify the duration of the transition, and the Fallback element allows clients that do not support this namespace to see an appropriate alternative representation. *end example*] + +More details on the P14 class can be found here: + +## How the Sample Code Works ## +After opening the presentation file for read/write access in the using statement, the code gets the presentation part from the presentation document. Then, it retrieves the relationship IDs of all slides in the presentation and gets the slides part from the relationship ID. The code then checks if there are no existing transitions set on the slides and replaces them with a new RandomBarTransition. + +### [C#](#tab/cs-2) +[!code-csharp[](../../samples/presentation/add_transition/cs/Program.cs#snippet2)] + +### [Visual Basic](#tab/vb-2) +[!code-vb[](../../samples/presentation/add_transition/vb/Program.vb#snippet2)] +*** + +If there are currently no transitions on the slide, code creates new transition. In both cases as a fallback transition, +RandomBarTransition is used but without `P14:dur`(duration) to allow grater support for clients that aren't supporting this namespace + +### [C#](#tab/cs-3) +[!code-csharp[](../../samples/presentation/add_transition/cs/Program.cs#snippet3)] + +### [Visual Basic](#tab/vb-3) +[!code-vb[](../../samples/presentation/add_transition/vb/Program.vb#snippet3)] +*** + +## Sample Code + +Following is the complete sample code that you can use to add RandomBarTransition to all slides. + +### [C#](#tab/cs) +[!code-csharp[](../../samples/presentation/add_transition/cs/Program.cs#snippet0)] + +### [Visual Basic](#tab/vb) +[!code-vb[](../../samples/presentation/add_transition/vb/Program.vb#snippet0)] +*** + +## See also + +- [Open XML SDK class library reference](/office/open-xml/open-xml-sdk) + + + + diff --git a/docs/presentation/how-to-apply-a-theme-to-a-presentation.md b/docs/presentation/how-to-apply-a-theme-to-a-presentation.md index 809babf2..ae640f93 100644 --- a/docs/presentation/how-to-apply-a-theme-to-a-presentation.md +++ b/docs/presentation/how-to-apply-a-theme-to-a-presentation.md @@ -11,7 +11,7 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 12/05/2023 ms.localizationpriority: medium --- @@ -25,11 +25,11 @@ programmatically. ----------------------------------------------------------------------------- ## Getting a PresentationDocument Object -In the Open XML SDK, the [PresentationDocument](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationdocument.aspx) class represents a +In the Open XML SDK, the class represents a presentation document package. To work with a presentation document, first create an instance of the **PresentationDocument** class, and then work with that instance. To create the class instance from the document call the -[Open(String, Boolean)](https://msdn.microsoft.com/library/office/cc562287.aspx) method that uses a + method that uses a file path, and a Boolean value as the second parameter to specify whether a document is editable. To open a document for read-only access, specify the value **false** for this parameter. @@ -44,31 +44,14 @@ that represents the path for the source presentation document, and the represents the path for the target presentation document. ### [C#](#tab/cs-0) -```csharp - using (PresentationDocument themeDocument = PresentationDocument.Open(themePresentation, false)) - using (PresentationDocument presentationDocument = PresentationDocument.Open(presentationFile, true)) - { - // Insert other code here. - } -``` +[!code-csharp[](../../samples/presentation/apply_a_theme_to/cs/Program.cs?name=snippet1)] ### [Visual Basic](#tab/vb-0) -```vb - Using themeDocument As PresentationDocument = PresentationDocument.Open(themePresentation, False) - Using presentationDocument As PresentationDocument = PresentationDocument.Open(presentationFile, True) - ' Insert other code here. - End Using - End Using -``` +[!code-vb[](../../samples/presentation/apply_a_theme_to/vb/Program.vb?name=snippet1)] *** -The **using** statement provides a recommended -alternative to the typical .Open, .Save, .Close sequence. It ensures -that the **Dispose** method (internal method -used by the Open XML SDK to clean up resources) is automatically called -when the closing brace is reached. The block that follows the **using** statement establishes a scope for the -object that is created or named in the **using** statement, in this case **themeDocument** and **presentationDocument**. + [!include[Using Statement](../includes/presentation/using-statement.md)] `themeDocument` and `presentationDocument`. ----------------------------------------------------------------------------- @@ -77,7 +60,7 @@ object that is created or named in the **using** statement, in this case **theme ----------------------------------------------------------------------------- ## Structure of the Theme Element -The following information from the [ISO/IEC 29500](https://www.iso.org/standard/71691.html) specification can +The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification can be useful when working with this element. > This element defines the root level complex type associated with a @@ -95,7 +78,7 @@ be useful when working with this element. > backgrounds, fills, and effects for different objects in a > presentation. *end example*] > -> © ISO/IEC29500: 2008. +> © [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] The following table lists the possible child types of the Theme class. @@ -141,29 +124,10 @@ files, **themePresentation** and **presentationFile**, are opened and passed to second overloaded method as parameters. ### [C#](#tab/cs-1) -```csharp - // Apply a new theme to the presentation. - public static void ApplyThemeToPresentation(string presentationFile, string themePresentation) - { - using (PresentationDocument themeDocument = PresentationDocument.Open(themePresentation, false)) - using (PresentationDocument presentationDocument = PresentationDocument.Open(presentationFile, true)) - { - ApplyThemeToPresentation(presentationDocument, themeDocument); - } - } -``` +[!code-csharp[](../../samples/presentation/apply_a_theme_to/cs/Program.cs?name=snippet2)] ### [Visual Basic](#tab/vb-1) -```vb - ' Apply a new theme to the presentation. - Public Shared Sub ApplyThemeToPresentation(ByVal presentationFile As String, ByVal themePresentation As String) - Using themeDocument As PresentationDocument = PresentationDocument.Open(themePresentation, False) - Using presentationDocument As PresentationDocument = PresentationDocument.Open(presentationFile, True) - ApplyThemeToPresentation(presentationDocument, themeDocument) - End Using - End Using - End Sub -``` +[!code-vb[](../../samples/presentation/apply_a_theme_to/vb/Program.vb?name=snippet2)] *** @@ -177,52 +141,10 @@ passed in, and gets the relationship ID of the slide master part of the target presentation. ### [C#](#tab/cs-2) -```csharp - // Apply a new theme to the presentation. - public static void ApplyThemeToPresentation(PresentationDocument presentationDocument, PresentationDocument themeDocument) - { - if (presentationDocument == null) - { - throw new ArgumentNullException("presentationDocument"); - } - if (themeDocument == null) - { - throw new ArgumentNullException("themeDocument"); - } - - // Get the presentation part of the presentation document. - PresentationPart presentationPart = presentationDocument.PresentationPart; - - // Get the existing slide master part. - SlideMasterPart slideMasterPart = presentationPart.SlideMasterParts.ElementAt(0); - string relationshipId = presentationPart.GetIdOfPart(slideMasterPart); - - // Get the new slide master part. - SlideMasterPart newSlideMasterPart = themeDocument.PresentationPart.SlideMasterParts.ElementAt(0); - } -``` +[!code-csharp[](../../samples/presentation/apply_a_theme_to/cs/Program.cs?name=snippet3)] ### [Visual Basic](#tab/vb-2) -```vb - Apply a new theme to the presentation. - Public Shared Sub ApplyThemeToPresentation(ByVal presentationDocument As PresentationDocument, ByVal themeDocument As PresentationDocument) - If presentationDocument Is Nothing Then - Throw New ArgumentNullException("presentationDocument") - End If - If themeDocument Is Nothing Then - Throw New ArgumentNullException("themeDocument") - End If - - ' Get the presentation part of the presentation document. - Dim presentationPart As PresentationPart = presentationDocument.PresentationPart - - ' Get the existing slide master part. - Dim slideMasterPart As SlideMasterPart = presentationPart.SlideMasterParts.ElementAt(0) - Dim relationshipId As String = presentationPart.GetIdOfPart(slideMasterPart) - - ' Get the new slide master part. - Dim newSlideMasterPart As SlideMasterPart = themeDocument.PresentationPart.SlideMasterParts.ElementAt(0) -``` +[!code-vb[](../../samples/presentation/apply_a_theme_to/vb/Program.vb?name=snippet3)] *** @@ -233,34 +155,10 @@ target presentation. It also adds the theme part to the target presentation. ### [C#](#tab/cs-3) -```csharp - // Remove the existing theme part. - presentationPart.DeletePart(presentationPart.ThemePart); - - // Remove the old slide master part. - presentationPart.DeletePart(slideMasterPart); - - // Import the new slide master part, and reuse the old relationship ID. - newSlideMasterPart = presentationPart.AddPart(newSlideMasterPart, relationshipId); - - // Change to the new theme part. - presentationPart.AddPart(newSlideMasterPart.ThemePart); -``` +[!code-csharp[](../../samples/presentation/apply_a_theme_to/cs/Program.cs?name=snippet4)] ### [Visual Basic](#tab/vb-3) -```vb - ' Remove the existing theme part. - presentationPart.DeletePart(presentationPart.ThemePart) - - ' Remove the old slide master part. - presentationPart.DeletePart(slideMasterPart) - - ' Import the new slide master part, and reuse the old relationship ID. - newSlideMasterPart = presentationPart.AddPart(newSlideMasterPart, relationshipId) - - ' Change to the new theme part. - presentationPart.AddPart(newSlideMasterPart.ThemePart) -``` +[!code-vb[](../../samples/presentation/apply_a_theme_to/vb/Program.vb?name=snippet4)] *** @@ -270,35 +168,10 @@ default layout type. For this example, the code for the default layout type is "Title and Content". ### [C#](#tab/cs-4) -```csharp - Dictionary newSlideLayouts = new Dictionary(); - - foreach (var slideLayoutPart in newSlideMasterPart.SlideLayoutParts) - { - newSlideLayouts.Add(GetSlideLayoutType(slideLayoutPart), slideLayoutPart); - } - - string layoutType = null; - SlideLayoutPart newLayoutPart = null; - - // Insert the code for the layout for this example. - string defaultLayoutType = "Title and Content"; -``` +[!code-csharp[](../../samples/presentation/apply_a_theme_to/cs/Program.cs?name=snippet5)] ### [Visual Basic](#tab/vb-4) -```vb - Dim newSlideLayouts As New Dictionary(Of String, SlideLayoutPart)() - - For Each slideLayoutPart In newSlideMasterPart.SlideLayoutParts - newSlideLayouts.Add(GetSlideLayoutType(slideLayoutPart), slideLayoutPart) - Next slideLayoutPart - - Dim layoutType As String = Nothing - Dim newLayoutPart As SlideLayoutPart = Nothing - - ' Insert the code for the layout for this example. - Dim defaultLayoutType As String = "Title and Content" -``` +[!code-vb[](../../samples/presentation/apply_a_theme_to/vb/Program.vb?name=snippet5)] *** @@ -311,90 +184,22 @@ had previously. For any slide without an existing slide layout part, it adds a new slide layout part of the default type. ### [C#](#tab/cs-5) -```csharp - // Remove the slide layout relationship on all slides. - foreach (var slidePart in presentationPart.SlideParts) - { - layoutType = null; - - if (slidePart.SlideLayoutPart != null) - { - // Determine the slide layout type for each slide. - layoutType = GetSlideLayoutType(slidePart.SlideLayoutPart); - - // Delete the old layout part. - slidePart.DeletePart(slidePart.SlideLayoutPart); - } - - if (layoutType != null && newSlideLayouts.TryGetValue(layoutType, out newLayoutPart)) - { - // Apply the new layout part. - slidePart.AddPart(newLayoutPart); - } - else - { - newLayoutPart = newSlideLayouts[defaultLayoutType]; - - // Apply the new default layout part. - slidePart.AddPart(newLayoutPart); - } - } -``` +[!code-csharp[](../../samples/presentation/apply_a_theme_to/cs/Program.cs?name=snippet6)] ### [Visual Basic](#tab/vb-5) -```vb - ' Remove the slide layout relationship on all slides. - For Each slidePart In presentationPart.SlideParts - layoutType = Nothing - - If slidePart.SlideLayoutPart IsNot Nothing Then - ' Determine the slide layout type for each slide. - layoutType = GetSlideLayoutType(slidePart.SlideLayoutPart) - - ' Delete the old layout part. - slidePart.DeletePart(slidePart.SlideLayoutPart) - End If - - If layoutType IsNot Nothing AndAlso newSlideLayouts.TryGetValue(layoutType, newLayoutPart) Then - ' Apply the new layout part. - slidePart.AddPart(newLayoutPart) - Else - newLayoutPart = newSlideLayouts(defaultLayoutType) - - ' Apply the new default layout part. - slidePart.AddPart(newLayoutPart) - End If - Next slidePart -`` +[!code-vb[](../../samples/presentation/apply_a_theme_to/vb/Program.vb?name=snippet6)] +*** To get the type of the slide layout, the code uses the **GetSlideLayoutType** method that takes the slide layout part as a parameter, and returns to the second overloaded **ApplyThemeToPresentation** method a string that represents the name of the slide layout type -``csharp - // Get the slide layout type. - public static string GetSlideLayoutType(SlideLayoutPart slideLayoutPart) - { - CommonSlideData slideData = slideLayoutPart.SlideLayout.CommonSlideData; - - // Remarks: If this is used in production code, check for a null reference. +### [C#](#tab/cs-6) +[!code-csharp[](../../samples/presentation/apply_a_theme_to/cs/Program.cs?name=snippet7)] - return slideData.Name;} -``` +### [Visual Basic](#tab/vb-6) +[!code-vb[](../../samples/presentation/apply_a_theme_to/vb/Program.vb?name=snippet7)] *** - - -```vb - ' Get the slide layout type. - Public Shared Function GetSlideLayoutType(ByVal slideLayoutPart As SlideLayoutPart) As String - Dim slideData As CommonSlideData = slideLayoutPart.SlideLayout.CommonSlideData - - ' Remarks: If this is used in production code, check for a null reference. - - Return slideData.Name - End Function -``` - ----------------------------------------------------------------------------- ## Sample Code The following is the complete sample code to copy a theme from one @@ -404,19 +209,11 @@ copy, for example, Myppt9-theme.pptx, and the other one is the target presentation, for example, Myppt9.pptx. You can use the following call in your program to perform the copying. -### [C#](#tab/cs-6) -```csharp - string presentationFile=@"C:\Users\Public\Documents\myppt2.pptx"; - string themePresentation = @"C:\Users\Public\Documents\myppt2-theme.pptx"; - ApplyThemeToPresentation(presentationFile, themePresentation); -``` +### [C#](#tab/cs-7) +[!code-csharp[](../../samples/presentation/apply_a_theme_to/cs/Program.cs?name=snippet8)] -### [Visual Basic](#tab/vb-6) -```vb - Dim presentationFile As String = "C:\Users\Public\Documents\myppt2.pptx" - Dim themePresentation As String = "C:\Users\Public\Documents\myppt2-theme.pptx" - ApplyThemeToPresentation(presentationFile, themePresentation) -``` +### [Visual Basic](#tab/vb-7) +[!code-vb[](../../samples/presentation/apply_a_theme_to/vb/Program.vb?name=snippet8)] *** @@ -424,10 +221,10 @@ After performing that call you can inspect the file Myppt2.pptx, and you would see the same theme of the file Myppt9-theme.pptx. ### [C#](#tab/cs) -[!code-csharp[](../../samples/presentation/apply_a_theme_to/cs/Program.cs)] +[!code-csharp[](../../samples/presentation/apply_a_theme_to/cs/Program.cs?name=snippet9)] ### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/presentation/apply_a_theme_to/vb/Program.vb)] +[!code-vb[](../../samples/presentation/apply_a_theme_to/vb/Program.vb?name=snippet9)] ----------------------------------------------------------------------------- ## See also diff --git a/docs/presentation/how-to-change-the-fill-color-of-a-shape-in-a-presentation.md b/docs/presentation/how-to-change-the-fill-color-of-a-shape-in-a-presentation.md index c6dd62ac..a3380383 100644 --- a/docs/presentation/how-to-change-the-fill-color-of-a-shape-in-a-presentation.md +++ b/docs/presentation/how-to-change-the-fill-color-of-a-shape-in-a-presentation.md @@ -11,7 +11,7 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 01/02/2025 ms.localizationpriority: medium --- @@ -25,60 +25,43 @@ programmatically. ## Getting a Presentation Object -In the Open XML SDK, the **PresentationDocument** class represents a +In the Open XML SDK, the `PresentationDocument` class represents a presentation document package. To work with a presentation document, -first create an instance of the **PresentationDocument** class, and then work with +first create an instance of the `PresentationDocument` class, and then work with that instance. To create the class instance from the document call the -**Open** method that uses a file path, and a +`Open` method that uses a file path, and a Boolean value as the second parameter to specify whether a document is -editable. To open a document for read/write, specify the value **true** for this parameter as shown in the following -**using** statement. In this code, the file +editable. To open a document for read/write, specify the value `true` for this parameter as shown in the following +`using` statement. In this code, the file parameter is a string that represents the path for the file from which you want to open the document. -### [C#](#tab/cs-0) -```csharp - using (PresentationDocument ppt = PresentationDocument.Open(docName, true)) - { - // Insert other code here. - } -``` +### [C#](#tab/cs-1) +[!code-csharp[](../../samples/presentation/change_the_fill_color_of_a_shape/cs/Program.cs#snippet1)] -### [Visual Basic](#tab/vb-0) -```vb - Using ppt As PresentationDocument = PresentationDocument.Open(docName, True) - ' Insert other code here. - End Using -``` +### [Visual Basic](#tab/vb-1) +[!code-vb[](../../samples/presentation/change_the_fill_color_of_a_shape/vb/Program.vb#snippet1)] *** -The **using** statement provides a recommended -alternative to the typical .Open, .Save, .Close sequence. It ensures -that the **Dispose** method (internal method -used by the Open XML SDK to clean up resources) is automatically called -when the closing brace is reached. The block that follows the **using** statement establishes a scope for the -object that is created or named in the **using** statement, in this case *ppt*. +[!include[Using Statement](../includes/presentation/using-statement.md)] `ppt`. ## The Structure of the Shape Tree The basic document structure of a PresentationML document consists of a -number of parts, among which is the Shape Tree (**sp -Tree**) element. +number of parts, among which is the Shape Tree (``) element. -The following text from the [ISO/IEC 29500](https://www.iso.org/standard/71691.html) specification -introduces the overall form of a **PresentationML** package. +The following text from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification +introduces the overall form of a `PresentationML` package. > This element specifies all shapes within a slide. Contained within > here are all the shapes, either grouped or not, that can be referenced > on a given slide. As most objects within a slide are shapes, this > represents the majority of content within a slide. Text and effects -> are attached to shapes that are contained within the class="keyword">spTree** element. +> are attached to shapes that are contained within the `spTree` element. > -> [*Example*: Consider the following class="keyword">PresentationML** slide +> [*Example*: Consider the following `PresentationML` slide ```xml @@ -102,7 +85,7 @@ introduces the overall form of a **PresentationML** package. > In the above example the shape tree specifies all the shape properties > for this slide. *end example*] > -> © ISO/IEC29500: 2008. +> © [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] The following table lists the child elements of the Shape Tree along with the description of each. @@ -139,134 +122,45 @@ The following XML Schema fragment defines the contents of this element. ## How the Sample Code Works -After opening the presentation file for read/write access in the **using** statement, the code gets the presentation +After opening the presentation file for read/write access in the `using` statement, the code gets the presentation part from the presentation document. Then it gets the relationship ID of the first slide, and gets the slide part from the relationship ID. > [!NOTE] -> The test file must have a filled shape as the first shape on the first slide. - -### [C#](#tab/cs-1) -```csharp - using (PresentationDocument ppt = PresentationDocument.Open(docName, true)) - { - // Get the relationship ID of the first slide. - PresentationPart part = ppt.PresentationPart; - OpenXmlElementList slideIds = part.Presentation.SlideIdList.ChildElements; - string relId = (slideIds[0] as SlideId).RelationshipId; - - // Get the slide part from the relationship ID. - SlidePart slide = (SlidePart)part.GetPartById(relId); -``` - -### [Visual Basic](#tab/vb-1) -```vb - Using ppt As PresentationDocument = PresentationDocument.Open(docName, True) - - ' Get the relationship ID of the first slide. - Dim part As PresentationPart = ppt.PresentationPart - Dim slideIds As OpenXmlElementList = part.Presentation.SlideIdList.ChildElements - Dim relId As String = CType(slideIds(0), SlideId).RelationshipId - - ' Get the slide part from the relationship ID. - Dim slide As SlidePart = CType(part.GetPartById(relId), SlidePart) -``` -*** - - -The code then gets the shape tree that contains the shape whose fill -color is to be changed, and gets the first shape in the shape tree. It -then gets the style of the shape and the fill reference of the style, -and assigns a new fill color to the shape. Finally it saves the modified -presentation. +> The test file must have a shape on the first slide. ### [C#](#tab/cs-2) -```csharp - if (slide != null) - { - // Get the shape tree that contains the shape to change. - ShapeTree tree = slide.Slide.CommonSlideData.ShapeTree; - - // Get the first shape in the shape tree. - Shape shape = tree.GetFirstChild(); - - if (shape != null) - { - // Get the style of the shape. - ShapeStyle style = shape.ShapeStyle; - - // Get the fill reference. - Drawing.FillReference fillRef = style.FillReference; - - // Set the fill color to SchemeColor Accent 6; - fillRef.SchemeColor = new Drawing.SchemeColor(); - fillRef.SchemeColor.Val = Drawing.SchemeColorValues.Accent6; - - // Save the modified slide. - slide.Slide.Save(); - } - } -``` +[!code-csharp[](../../samples/presentation/change_the_fill_color_of_a_shape/cs/Program.cs#snippet2)] ### [Visual Basic](#tab/vb-2) -```vb - If (Not (slide) Is Nothing) Then - - ' Get the shape tree that contains the shape to change. - Dim tree As ShapeTree = slide.Slide.CommonSlideData.ShapeTree - - ' Get the first shape in the shape tree. - Dim shape As Shape = tree.GetFirstChild(Of Shape)() - - If (Not (shape) Is Nothing) Then - - ' Get the style of the shape. - Dim style As ShapeStyle = shape.ShapeStyle - - ' Get the fill reference. - Dim fillRef As Drawing.FillReference = style.FillReference - - ' Set the fill color to SchemeColor Accent 6; - fillRef.SchemeColor = New Drawing.SchemeColor - fillRef.SchemeColor.Val = Drawing.SchemeColorValues.Accent6 - - ' Save the modified slide. - slide.Slide.Save() - End If - End If -``` +[!code-vb[](../../samples/presentation/change_the_fill_color_of_a_shape/vb/Program.vb#snippet2)] *** -## Sample Code - -Following is the complete sample code that you can use to change the -fill color of a shape in a presentation. In your program, you can invoke -the method **SetPPTShapeColor** to change the -fill color in the file "Myppt3.pptx" by using the following call. +The code then gets the shape tree that contains the shape whose fill +color is to be changed, and gets the first shape in the shape tree. It +then gets the shape properties of the shape and the solid fill reference of the shape properties, +and assigns a new fill color to the shape. There is no need to explicitly +save the file when inside of a using. ### [C#](#tab/cs-3) -```csharp - string docName = @"C:\Users\Public\Documents\Myppt3.pptx"; - SetPPTShapeColor(docName); -``` +[!code-csharp[](../../samples/presentation/change_the_fill_color_of_a_shape/cs/Program.cs#snippet3)] ### [Visual Basic](#tab/vb-3) -```vb - Dim docName As String = "C:\Users\Public\Documents\Myppt3.pptx" - SetPPTShapeColor(docName) -``` +[!code-vb[](../../samples/presentation/change_the_fill_color_of_a_shape/vb/Program.vb#snippet3)] *** -After running the program, examine the file "Myppt3.pptx" to see the -change in the fill color. +## Sample Code +Following is the complete sample code that you can use to change the +fill color of a shape in a presentation. ### [C#](#tab/cs) -[!code-csharp[](../../samples/presentation/change_the_fill_color_of_a_shape/cs/Program.cs)] +[!code-csharp[](../../samples/presentation/change_the_fill_color_of_a_shape/cs/Program.cs#snippet0)] ### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/presentation/change_the_fill_color_of_a_shape/vb/Program.vb)] +[!code-vb[](../../samples/presentation/change_the_fill_color_of_a_shape/vb/Program.vb#snippet0)] +*** ## See also diff --git a/docs/presentation/how-to-create-a-presentation-document-by-providing-a-file-name.md b/docs/presentation/how-to-create-a-presentation-document-by-providing-a-file-name.md index 5f76541e..8ad5735f 100644 --- a/docs/presentation/how-to-create-a-presentation-document-by-providing-a-file-name.md +++ b/docs/presentation/how-to-create-a-presentation-document-by-providing-a-file-name.md @@ -12,7 +12,7 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 06/28/2021 +ms.date: 12/31/2024 ms.localizationpriority: high --- @@ -30,69 +30,59 @@ create a presentation document programmatically. A presentation file, like all files defined by the Open XML standard, consists of a package file container. This is the file that users see in their file explorer; it usually has a .pptx extension. The package file -is represented in the Open XML SDK by the [PresentationDocument](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationdocument.aspx) class. The +is represented in the Open XML SDK by the class. The presentation document contains, among other parts, a presentation part. -The presentation part, represented in the Open XML SDK by the [PresentationPart](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationpart.aspx) class, contains the basic +The presentation part, represented in the Open XML SDK by the class, contains the basic *PresentationML* definition for the slide presentation. PresentationML is the markup language used for creating presentations. Each package can -contain only one presentation part, and its root element must be -\. +contain only one presentation part, and its root element must be ``. The API calls used to create a new presentation document package are -relatively simple. The first step is to call the static [Create(String,PresentationDocumentType)](https://msdn.microsoft.com/library/office/cc535977.aspx) -method of the [PresentationDocument](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationdocument.aspx) class, as shown here -in the **CreatePresentation** procedure, which is the first part of the +relatively simple. The first step is to call the static +method of the class, as shown here +in the `CreatePresentation` procedure, which is the first part of the complete code sample presented later in the article. The -**CreatePresentation** code calls the override of the **Create** method that takes as arguments the path to +`CreatePresentation` code calls the override of the `Create` method that takes as arguments the path to the new document and the type of presentation document to be created. The types of presentation documents available in that argument are -defined by a [PresentationDocumentType](https://msdn.microsoft.com/library/office/documentformat.openxml.presentationdocumenttype.aspx) enumerated value. +defined by a enumerated value. -Next, the code calls [AddPresentationPart()](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationdocument.addpresentationpart.aspx), which creates and -returns a **PresentationPart**. After the **PresentationPart** class instance is created, a new -root element for the presentation is added by setting the [Presentation](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationpart.presentation.aspx) property equal to the instance -of the [Presentation](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.presentation.aspx) class returned from a call to -the **Presentation** class constructor. +Next, the code calls , which creates and +returns a `PresentationPart`. After the `PresentationPart` class instance is created, a new +root element for the presentation is added by setting the property equal to the instance of the class returned from a call to +the `Presentation` class constructor. In order to create a complete, useable, and valid presentation, the code must also add a number of other parts to the presentation package. In the example code, this is taken care of by a call to a utility function -named **CreatePresentationsParts**. That function then calls a number of +named `CreatePresentationsParts`. That function then calls a number of other utility functions that, taken together, create all the presentation parts needed for a basic presentation, including slide, slide layout, slide master, and theme parts. -```csharp - public static void CreatePresentation(string filepath) - { - // Create a presentation at a specified file path. The presentation document type is pptx, by default. - PresentationDocument presentationDoc = PresentationDocument.Create(filepath, PresentationDocumentType.Presentation); - PresentationPart presentationPart = presentationDoc.AddPresentationPart(); - presentationPart.Presentation = new Presentation(); +### [C#](#tab/cs-1) +[!code-csharp[](../../samples/presentation/create_by_providing_a_file_name/cs/Program.cs#snippet1)] - CreatePresentationParts(presentationPart); - - // Close the presentation handle - presentationDoc.Close(); - } -``` +### [Visual Basic](#tab/vb-1) +[!code-vb[](../../samples/presentation/create_by_providing_a_file_name/vb/Program.vb#snippet1)] +*** Using the Open XML SDK, you can create presentation structure and content by using strongly-typed classes that correspond to -PresentationML elements. You can find these classes in the [DocumentFormat.OpenXml.Presentation](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.aspx) +PresentationML elements. You can find these classes in the namespace. The following table lists the names of the classes that correspond to the presentation, slide, slide master, slide layout, and theme elements. The class that corresponds to the theme element is -actually part of the [DocumentFormat.OpenXml.Drawing](https://msdn.microsoft.com/library/office/documentformat.openxml.drawing.aspx) namespace. +actually part of the namespace. Themes are common to all Open XML markup languages. | PresentationML Element | Open XML SDK Class | |---|---| -| <presentation> | [Presentation](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.presentation.aspx) | -| <sld> | [Slide](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.slide.aspx) | -| <sldMaster> | [SlideMaster](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.slidemaster.aspx) | -| <sldLayout> | [SlideLayout](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.slidelayout.aspx) | -| <theme> | [Theme](https://msdn.microsoft.com/library/office/documentformat.openxml.drawing.theme.aspx) | +| `` | | +| `` | | +| `` | | +| `` | | +| `` | | The PresentationML code that follows is the XML in the presentation part (in the file presentation.xml) for a simple presentation that contains @@ -126,10 +116,11 @@ Following is the complete sample C\# and VB code to create a presentation, given a file path. ### [C#](#tab/cs) -[!code-csharp[](../../samples/presentation/create_by_providing_a_file_name/cs/Program.cs)] +[!code-csharp[](../../samples/presentation/create_by_providing_a_file_name/cs/Program.cs#snippet0)] ### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/presentation/create_by_providing_a_file_name/vb/Program.vb)] +[!code-vb[](../../samples/presentation/create_by_providing_a_file_name/vb/Program.vb#snippet0)] +*** -------------------------------------------------------------------------------- diff --git a/docs/presentation/how-to-delete-a-slide-from-a-presentation.md b/docs/presentation/how-to-delete-a-slide-from-a-presentation.md index c03d56a5..a0b4a046 100644 --- a/docs/presentation/how-to-delete-a-slide-from-a-presentation.md +++ b/docs/presentation/how-to-delete-a-slide-from-a-presentation.md @@ -11,7 +11,7 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 12/31/2024 ms.localizationpriority: medium --- # Delete a slide from a presentation @@ -30,253 +30,92 @@ slides, and the second is deleting a slide at a specific index. -------------------------------------------------------------------------------- -## Getting a Presentation Object - -In the Open XML SDK, the **[PresentationDocument](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationdocument.aspx)** class represents a presentation document package. To work with a presentation document, first create an instance of the **PresentationDocument** class, and then work with that instance. To create the class instance from the document call one of the **Open** method overloads. The code in this topic uses the **[PresentationDocument.Open(String, Boolean)](https://msdn.microsoft.com/library/office/cc562287.aspx)** method, which takes a file path as the first parameter to specify the file to open, and a Boolean value as the second parameter to specify whether a document is editable. Set this second parameter to **false** to open the file for read-only access, or **true** if you want to open the file for read/write access. The code in this topic opens the file twice, once to count the number of slides and once to delete a specific slide. When you count the number of slides in a presentation, it is best to open the file for read-only access to protect the file against accidental writing. The following **using** statement opens the file for read-only access. In this code example, the **presentationFile** parameter is a string that represents the path for the file from which you want to open the document. - -### [C#](#tab/cs-0) -```csharp - // Open the presentation as read-only. - using (PresentationDocument presentationDocument = PresentationDocument.Open(presentationFile, false)) - { - // Insert other code here. - } -``` - -### [Visual Basic](#tab/vb-0) -```vb - ' Open the presentation as read-only. - Using presentationDocument As PresentationDocument = PresentationDocument.Open(presentationFile, False) - ' Insert other code here. - End Using -``` +## Getting a Presentation Object + +In the Open XML SDK, the class represents a presentation document package. To work with a presentation document, first create an instance of the `PresentationDocument` class, and then work with that instance. To create the class instance from the document call one of the `Open` method overloads. The code in this topic uses the method, which takes a file path as the first parameter to specify the file to open, and a Boolean value as the second parameter to specify whether a document is editable. Set this second parameter to `false` to open the file for read-only access, or `true` if you want to open the file for read/write access. The code in this topic opens the file twice, once to count the number of slides and once to delete a specific slide. When you count the number of slides in a presentation, it is best to open the file for read-only access to protect the file against accidental writing. The following `using` statement opens the file for read-only access. In this code example, the `presentationFile` parameter is a string that represents the path for the file from which you want to open the document. + +### [C#](#tab/cs-1) +[!code-csharp[](../../samples/presentation/delete_a_slide_from/cs/Program.cs#snippet1)] + +### [Visual Basic](#tab/vb-1) +[!code-vb[](../../samples/presentation/delete_a_slide_from/vb/Program.vb#snippet1)] *** To delete a slide from the presentation file, open it for read/write -access as shown in the following **using** +access as shown in the following `using` statement. -### [C#](#tab/cs-1) -```csharp - // Open the source document as read/write. - using (PresentationDocument presentationDocument = PresentationDocument.Open(presentationFile, true)) - { - // Place other code here. - } -``` +### [C#](#tab/cs-2) +[!code-csharp[](../../samples/presentation/delete_a_slide_from/cs/Program.cs#snippet2)] -### [Visual Basic](#tab/vb-1) -```vb - ' Open the source document as read/write. - Using presentationDocument As PresentationDocument = PresentationDocument.Open(presentationFile, True) - ' Place other code here. - End Using -``` +### [Visual Basic](#tab/vb-2) +[!code-vb[](../../samples/presentation/delete_a_slide_from/vb/Program.vb#snippet2)] *** -The **using** statement provides a recommended alternative to the typical .Open, .Save, .Close sequence. It ensures that the **Dispose** method (internal method used by the Open XML SDK to clean up resources) is automatically called when the closing brace is reached. The block that follows the **using** statement establishes a scope for the object that is created or named in the **using** statement, in this case **presentationDocument**. +[!include[Using Statement](../includes/presentation/using-statement.md)] `presentationDocument`. [!include[Structure](../includes/presentation/structure.md)] -## Counting the Number of Slides +## Counting the Number of Slides -The sample code consists of two overloads of the **CountSlides** method. The first overload uses a **string** parameter and the second overload uses a **PresentationDocument** parameter. In the first **CountSlides** method, the sample code opens the presentation document in the **using** statement. Then it passes the **PresentationDocument** object to the second **CountSlides** method, which returns an integer number that represents the number of slides in the presentation. +The sample code consists of two overloads of the `CountSlides` method. The first overload uses a `string` parameter and the second overload uses a `PresentationDocument` parameter. In the first `CountSlides` method, the sample code opens the presentation document in the `using` statement. Then it passes the `PresentationDocument` object to the second `CountSlides` method, which returns an integer number that represents the number of slides in the presentation. -### [C#](#tab/cs-2) -```csharp - // Pass the presentation to the next CountSlides method - // and return the slide count. - return CountSlides(presentationDocument); -``` +### [C#](#tab/cs-3) +[!code-csharp[](../../samples/presentation/delete_a_slide_from/cs/Program.cs#snippet3)] -### [Visual Basic](#tab/vb-2) -```vb - ' Pass the presentation to the next CountSlides method - ' and return the slide count. - Return CountSlides(presentationDocument) -``` +### [Visual Basic](#tab/vb-3) +[!code-vb[](../../samples/presentation/delete_a_slide_from/vb/Program.vb#snippet3)] *** -In the second **CountSlides** method, the code -verifies that the **PresentationDocument** -object passed in is not **null**, and if it is -not, it gets a **PresentationPart** object from -the **PresentationDocument** object. By using -the **SlideParts** the code gets the slideCount +In the second `CountSlides` method, the code +verifies that the `PresentationDocument` +object passed in is not `null`, and if it is +not, it gets a `PresentationPart` object from +the `PresentationDocument` object. By using +the `SlideParts` the code gets the slideCount and returns it. -### [C#](#tab/cs-3) -```csharp - // Check for a null document object. - if (presentationDocument == null) - { - throw new ArgumentNullException("presentationDocument"); - } - - int slidesCount = 0; - - // Get the presentation part of document. - PresentationPart presentationPart = presentationDocument.PresentationPart; - - // Get the slide count from the SlideParts. - if (presentationPart != null) - { - slidesCount = presentationPart.SlideParts.Count(); - } - // Return the slide count to the previous method. - return slidesCount; -``` +### [C#](#tab/cs-4) +[!code-csharp[](../../samples/presentation/delete_a_slide_from/cs/Program.cs#snippet4)] -### [Visual Basic](#tab/vb-3) -```vb - ' Check for a null document object. - If presentationDocument Is Nothing Then - Throw New ArgumentNullException("presentationDocument") - End If - - Dim slidesCount As Integer = 0 - - ' Get the presentation part of document. - Dim presentationPart As PresentationPart = presentationDocument.PresentationPart - - ' Get the slide count from the SlideParts. - If presentationPart IsNot Nothing Then - slidesCount = presentationPart.SlideParts.Count() - End If - ' Return the slide count to the previous method. - Return slidesCount -``` +### [Visual Basic](#tab/vb-4) +[!code-vb[](../../samples/presentation/delete_a_slide_from/vb/Program.vb#snippet4)] *** - -------------------------------------------------------------------------------- -## Deleting a Specific Slide +## Deleting a Specific Slide -The code for deleting a slide uses two overloads of the **DeleteSlide** method. The first overloaded **DeleteSlide** method takes two parameters: a string +The code for deleting a slide uses two overloads of the `DeleteSlide` method. The first overloaded `DeleteSlide` method takes two parameters: a string that represents the presentation file name and path, and an integer that represents the zero-based index position of the slide to delete. It -opens the presentation file for read/write access, gets a **PresentationDocument** object, and then passes that -object and the index number to the next overloaded **DeleteSlide** method, which performs the deletion. +opens the presentation file for read/write access, gets a `PresentationDocument` object, and then passes that +object and the index number to the next overloaded `DeleteSlide` method, which performs the deletion. -### [C#](#tab/cs-4) -```csharp - // Get the presentation object and pass it to the next DeleteSlide method. - public static void DeleteSlide(string presentationFile, int slideIndex) - { - // Open the source document as read/write. - - using (PresentationDocument presentationDocument = PresentationDocument.Open(presentationFile, true)) - { - // Pass the source document and the index of the slide to be deleted to the next DeleteSlide method. - DeleteSlide(presentationDocument, slideIndex); - } - } -``` +### [C#](#tab/cs-5) +[!code-csharp[](../../samples/presentation/delete_a_slide_from/cs/Program.cs#snippet5)] -### [Visual Basic](#tab/vb-4) -```vb - ' Check for a null document object. - If presentationDocument Is Nothing Then - Throw New ArgumentNullException("presentationDocument") - End If - - Dim slidesCount As Integer = 0 - - ' Get the presentation part of document. - Dim presentationPart As PresentationPart = presentationDocument.PresentationPart - - ' Get the slide count from the SlideParts. - If presentationPart IsNot Nothing Then - slidesCount = presentationPart.SlideParts.Count() - End If - ' Return the slide count to the previous method. - Return slidesCount -``` +### [Visual Basic](#tab/vb-5) +[!code-vb[](../../samples/presentation/delete_a_slide_from/vb/Program.vb#snippet5)] *** -The first section of the second overloaded **DeleteSlide** method uses the **CountSlides** method to get the number of slides in +The first section of the second overloaded `DeleteSlide` method uses the `CountSlides` method to get the number of slides in the presentation. Then, it gets the list of slide IDs in the presentation, identifies the specified slide in the slide list, and removes the slide from the slide list. -### [C#](#tab/cs-5) -```csharp - // Delete the specified slide from the presentation. - public static void DeleteSlide(PresentationDocument presentationDocument, int slideIndex) - { - if (presentationDocument == null) - { - throw new ArgumentNullException("presentationDocument"); - } - - // Use the CountSlides sample to get the number of slides in the presentation. - int slidesCount = CountSlides(presentationDocument); - - if (slideIndex < 0 || slideIndex >= slidesCount) - { - throw new ArgumentOutOfRangeException("slideIndex"); - } - - // Get the presentation part from the presentation document. - PresentationPart presentationPart = presentationDocument.PresentationPart; - - // Get the presentation from the presentation part. - Presentation presentation = presentationPart.Presentation; - - // Get the list of slide IDs in the presentation. - SlideIdList slideIdList = presentation.SlideIdList; - - // Get the slide ID of the specified slide - SlideId slideId = slideIdList.ChildElements[slideIndex] as SlideId; - - // Get the relationship ID of the slide. - string slideRelId = slideId.RelationshipId; - - // Remove the slide from the slide list. - slideIdList.RemoveChild(slideId); -``` - -### [Visual Basic](#tab/vb-5) -```vb - ' Delete the specified slide from the presentation. - Public Shared Sub DeleteSlide(ByVal presentationDocument As - If presentationDocument Is Nothing Then - Throw New ArgumentNullException("presentationDocument") - End If - - ' Use the CountSlides sample to get the number of slides in the presentation. - Dim slidesCount As Integer = CountSlides(presentationDocument) - - If slideIndex < 0 OrElse slideIndex >= slidesCount Then - Throw New ArgumentOutOfRangeException("slideIndex") - End If - - ' Get the presentation part from the presentation document. - Dim presentationPart As PresentationPart = presentationDocument.PresentationPart - - ' Get the presentation from the presentation part. - Dim presentation As Presentation = presentationPart.Presentation - - ' Get the list of slide IDs in the presentation. - Dim slideIdList As SlideIdList = presentation.SlideIdList - - ' Get the slide ID of the specified slide - Dim slideId As SlideId = TryCast(slideIdList.ChildElements(slideIndex), SlideId) - - ' Get the relationship ID of the slide. - Dim slideRelId As String = slideId.RelationshipId +### [C#](#tab/cs-6) +[!code-csharp[](../../samples/presentation/delete_a_slide_from/cs/Program.cs#snippet6)] - ' Remove the slide from the slide list. - slideIdList.RemoveChild(slideId) -``` +### [Visual Basic](#tab/vb-6) +[!code-vb[](../../samples/presentation/delete_a_slide_from/vb/Program.vb#snippet6)] *** -The next section of the second overloaded **DeleteSlide** method removes all references to the +The next section of the second overloaded `DeleteSlide` method removes all references to the deleted slide from custom shows. It does that by iterating through the list of custom shows and through the list of slides in each custom show. It then declares and instantiates a linked list of slide list entries, @@ -285,145 +124,38 @@ of that slide. It adds those references to the list of slide list entries, and then removes each such reference from the slide list of its respective custom show. -### [C#](#tab/cs-6) -```csharp - // Remove references to the slide from all custom shows. - if (presentation.CustomShowList != null) - { - // Iterate through the list of custom shows. - foreach (var customShow in presentation.CustomShowList.Elements()) - { - if (customShow.SlideList != null) - { - // Declare a link list of slide list entries. - LinkedList slideListEntries = new LinkedList(); - foreach (SlideListEntry slideListEntry in customShow.SlideList.Elements()) - { - // Find the slide reference to remove from the custom show. - if (slideListEntry.Id != null && slideListEntry.Id == slideRelId) - { - slideListEntries.AddLast(slideListEntry); - } - } - - // Remove all references to the slide from the custom show. - foreach (SlideListEntry slideListEntry in slideListEntries) - { - customShow.SlideList.RemoveChild(slideListEntry); - } - } - } - } -``` - -### [Visual Basic](#tab/vb-6) -```vb - ' Remove references to the slide from all custom shows. - If presentation.CustomShowList IsNot Nothing Then - ' Iterate through the list of custom shows. - For Each customShow In presentation.CustomShowList.Elements(Of CustomShow)() - If customShow.SlideList IsNot Nothing Then - ' Declare a link list of slide list entries. - Dim slideListEntries As New LinkedList(Of SlideListEntry)() - For Each slideListEntry As SlideListEntry In customShow.SlideList.Elements() - ' Find the slide reference to remove from the custom show. - If slideListEntry.Id IsNot Nothing AndAlso slideListEntry.Id = slideRelId Then - slideListEntries.AddLast(slideListEntry) - End If - Next slideListEntry - - ' Remove all references to the slide from the custom show. - For Each slideListEntry As SlideListEntry In slideListEntries - customShow.SlideList.RemoveChild(slideListEntry) - Next slideListEntry - End If - Next customShow - End If -``` -*** - - -Finally, the code saves the modified presentation, and deletes the slide -part for the deleted slide. - ### [C#](#tab/cs-7) -```csharp - // Save the modified presentation. - presentation.Save(); - - // Get the slide part for the specified slide. - SlidePart slidePart = presentationPart.GetPartById(slideRelId) as SlidePart; - - // Remove the slide part. - presentationPart.DeletePart(slidePart); - } -``` +[!code-csharp[](../../samples/presentation/delete_a_slide_from/cs/Program.cs#snippet7)] ### [Visual Basic](#tab/vb-7) -```vb - ' Save the modified presentation. - presentation.Save() - - ' Get the slide part for the specified slide. - Dim slidePart As SlidePart = TryCast(presentationPart.GetPartById(slideRelId), SlidePart) - - ' Remove the slide part. - presentationPart.DeletePart(slidePart) - End Sub -``` +[!code-vb[](../../samples/presentation/delete_a_slide_from/vb/Program.vb#snippet7)] *** --------------------------------------------------------------------------------- -## Sample Code - -The following is the complete sample code for the two overloaded -methods, **CountSlides** and **DeleteSlide**. To use the code, you can use the -following call as an example to delete the slide at index 2 in the -presentation file "Myppt6.pptx." +Finally, the code deletes the slide part for the deleted slide. ### [C#](#tab/cs-8) -```csharp - DeleteSlide(@"C:\Users\Public\Documents\Myppt6.pptx", 2); -``` +[!code-csharp[](../../samples/presentation/delete_a_slide_from/cs/Program.cs#snippet8)] ### [Visual Basic](#tab/vb-8) -```vb - DeleteSlide("C:\Users\Public\Documents\Myppt6.pptx", 0) -``` +[!code-vb[](../../samples/presentation/delete_a_slide_from/vb/Program.vb#snippet8)] *** -You can also use the following call to count the number of slides in the -presentation. - -### [C#](#tab/cs-9) -```csharp - Console.WriteLine("Number of slides = {0}", - CountSlides(@"C:\Users\Public\Documents\Myppt6.pptx")); -``` - -### [Visual Basic](#tab/vb-9) -```vb - Console.WriteLine("Number of slides = {0}", _ - CountSlides("C:\Users\Public\Documents\Myppt6.pptx")) -``` -*** - - -It might be a good idea to count the number of slides before and after -performing the deletion. +-------------------------------------------------------------------------------- +## Sample Code Following is the complete sample code in both C\# and Visual Basic. ### [C#](#tab/cs) -[!code-csharp[](../../samples/presentation/delete_a_slide_from/cs/Program.cs)] +[!code-csharp[](../../samples/presentation/delete_a_slide_from/cs/Program.cs#snippet0)] ### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/presentation/delete_a_slide_from/vb/Program.vb)] +[!code-vb[](../../samples/presentation/delete_a_slide_from/vb/Program.vb#snippet0)] +*** -------------------------------------------------------------------------------- -## See also +## See also diff --git a/docs/presentation/how-to-delete-all-the-comments-by-an-author-from-all-the-slides-in-a-presentatio.md b/docs/presentation/how-to-delete-all-the-comments-by-an-author-from-all-the-slides-in-a-presentatio.md deleted file mode 100644 index 038d5b45..00000000 --- a/docs/presentation/how-to-delete-all-the-comments-by-an-author-from-all-the-slides-in-a-presentatio.md +++ /dev/null @@ -1,271 +0,0 @@ ---- - -api_name: -- Microsoft.Office.DocumentFormat.OpenXML.Packaging -api_type: -- schema -ms.assetid: 3b892a6a-2972-461e-94a9-0a1ede854bda -title: 'Delete all the comments by an author from all the slides in a presentation' -ms.suite: office - -ms.author: o365devx -author: o365devx -ms.topic: conceptual -ms.date: 11/01/2017 -ms.localizationpriority: medium ---- -# Delete all the comments by an author from all the slides in a presentation - -This topic shows how to use the classes in the Open XML SDK for -Office to delete all of the comments by a specific author in a -presentation programmatically. - - - -## Getting a PresentationDocument Object - -In the Open XML SDK, the [PresentationDocument](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationdocument.aspx) class represents a -presentation document package. To work with a presentation document, -first create an instance of the **PresentationDocument** class, and then work with -that instance. To create the class instance from the document call the -[Open(String, Boolean)](https://msdn.microsoft.com/library/office/cc562287.aspx) method that uses a -file path, and a Boolean value as the second parameter to specify -whether a document is editable. To open a document for read/write, -specify the value **true** for this parameter -as shown in the following **using** statement. -In this code, the *fileName* parameter is a string that represents the -path for the file from which you want to open the document, and the -author is the user name displayed in the General tab of the PowerPoint -Options. - -### [C#](#tab/cs-0) -```csharp - public static void DeleteCommentsByAuthorInPresentation(string fileName, string author) - { - using (PresentationDocument doc = PresentationDocument.Open(fileName, true)) - { - // Insert other code here. - } -``` - -### [Visual Basic](#tab/vb-0) -```vb - Public Shared Sub DeleteCommentsByAuthorInPresentation(ByVal fileName As String, ByVal author As String) - - Using doc As PresentationDocument = PresentationDocument.Open(fileName, True) - ' Insert other code here. - End Using -``` -*** - - -The **using** statement provides a recommended -alternative to the typical .Open, .Save, .Close sequence. It ensures -that the **Dispose** method (internal method -used by the Open XML SDK to clean up resources) is automatically called -when the closing brace is reached. The block that follows the **using** statement establishes a scope for the -object that is created or named in the **using** statement, in this case *doc*. - -[!include[Structure](../includes/presentation/structure.md)] - -## The Structure of the Comment Element - -The following text from the [ISO/IEC 29500](https://www.iso.org/standard/71691.html) specification -introduces comments in a presentation package. - -> A comment is a text note attached to a slide, with the primary purpose -> of allowing readers of a presentation to provide feedback to the -> presentation author. Each comment contains an unformatted text string -> and information about its author, and is attached to a particular -> location on a slide. Comments can be visible while editing the -> presentation, but do not appear when a slide show is given. The -> displaying application decides when to display comments and determines -> their visual appearance. -> -> © ISO/IEC29500: 2008. - -The following XML element specifies a single comment attached to a -slide. It contains the text of the comment (**text**), its position on the slide (**pos**), and attributes referring to its author -(**authorId**), date and time (**dt**), and comment index (**idx**). - -```xml - - - Add diagram to clarify. - -``` - -The following table lists the definitions of the members and attributes -of the **cm** (comment) element. - -| Member/Attribute | Definition | -|---|---| -| authorId | Refers to the ID of an author in the comment author list for the document. | -| dt | The date and time this comment was last modified. | -| idx | An identifier for this comment that is unique within a list of all comments by this author in this document. An author's first comment in a document has index 1. | -| pos | The positioning information for the placement of a comment on a slide surface. | -| text | Comment's text content. | -| extLst | Specifies the extension list with modification ability within which all future extensions of element type ext are defined. The extension list along with corresponding future extensions is used to extend the storage capabilities of the PresentationML framework. This allows for various new kinds of data to be stored natively within the framework. | - -The following XML schema example defines the members of the **cm** element in addition to the required and -optional attributes. - -```xml - - - - - - - - - - -``` - -## How the Sample Code Works - -After opening the presentation document for read/write access and -instantiating the **PresentationDocument** -class, the code gets the specified comment author from the list of -comment authors. - -### [C#](#tab/cs-1) -```csharp - // Get the specifed comment author. - IEnumerable commentAuthors = - doc.PresentationPart.CommentAuthorsPart.CommentAuthorList.Elements() - .Where(e => e.Name.Value.Equals(author)); -``` - -### [Visual Basic](#tab/vb-1) -```vb - ' Get the specifed comment author. - Dim commentAuthors As IEnumerable(Of CommentAuthor) = _ - doc.PresentationPart.CommentAuthorsPart.CommentAuthorList.Elements _ - (Of CommentAuthor)().Where(Function(e) e.Name.Value.Equals(author)) -``` -*** - - -By iterating through the matching authors and all the slides in the -presentation the code gets all the slide parts, and the comments part of -each slide part. It then gets the list of comments by the specified -author and deletes each one. It also verifies that the comment part has -no existing comment, in which case it deletes that part. It also deletes -the comment author from the comment authors part. - -### [C#](#tab/cs-2) -```csharp - // Iterate through all the matching authors. - foreach (CommentAuthor commentAuthor in commentAuthors) - { - UInt32Value authorId = commentAuthor.Id; - - // Iterate through all the slides and get the slide parts. - foreach (SlidePart slide in doc.PresentationPart.SlideParts) - { - SlideCommentsPart slideCommentsPart = slide.SlideCommentsPart; - // Get the list of comments. - if (slideCommentsPart != null && slide.SlideCommentsPart.CommentList != null) - { - IEnumerable commentList = - slideCommentsPart.CommentList.Elements().Where(e => e.AuthorId == authorId.Value); - List comments = new List(); - comments = commentList.ToList(); - - foreach (Comment comm in comments) - { - // Delete all the comments by the specified author. - slideCommentsPart.CommentList.RemoveChild(comm); - } - - // If the commentPart has no existing comment. - if (slideCommentsPart.CommentList.ChildElements.Count == 0) - // Delete this part. - slide.DeletePart(slideCommentsPart); - } - } - // Delete the comment author from the comment authors part. - doc.PresentationPart.CommentAuthorsPart.CommentAuthorList.RemoveChild(commentAuthor); - } -``` - -### [Visual Basic](#tab/vb-2) -```vb - 'Iterate through all the matching authors - For Each commentAuthor In commentAuthors - - Dim authorId = commentAuthor.Id - - ' Iterate through all the slides and get the slide parts. - For Each slide In doc.PresentationPart.GetPartsOfType(Of SlidePart)() - - ' Get the slide comments part of each slide. - For Each slideCommentsPart In slide.GetPartsOfType(Of SlideCommentsPart)() - - ' Delete all the comments by the specified author. - Dim commentList = slideCommentsPart.CommentList.Elements(Of Comment)(). _ - Where(Function(e) e.AuthorId.Value.Equals(authorId.Value)) - - Dim comments As List(Of Comment) = commentList.ToList() - - For Each comm As Comment In comments - slideCommentsPart.CommentList.RemoveChild(Of Comment)(comm) - Next - - Next - - Next - - ' Delete the comment author from the comment authors part. - doc.PresentationPart.CommentAuthorsPart.CommentAuthorList.RemoveChild(Of CommentAuthor)(commentAuthor) - - Next -``` -*** - - -## Sample Code - -The following method takes as parameters the source presentation file -name and path and the name of the comment author whose comments are to -be deleted. It finds all the comments by the specified author in the -presentation and deletes them. It then deletes the comment author from -the list of comment authors. - -You can use the following example to call the -*DeleteCommentsByAuthorInPresentation* method to remove the comments of -the specified author from the presentation file, *myppt5.pptx*. - -### [C#](#tab/cs-3) -```csharp - string fileName = @"C:\Users\Public\Documents\myppt5.pptx"; - string author = "Katie Jordan"; - DeleteCommentsByAuthorInPresentation(fileName, author); -``` - -### [Visual Basic](#tab/vb-3) -```vb - Dim fileName As String = "C:\Users\Public\Documents\myppt5.pptx" - Dim author As String = "Katie Jordan" - DeleteCommentsByAuthorInPresentation(fileName, author) -``` -*** - -> [!NOTE] -> To get the exact author's name, open the presentation file and click the **File** menu item, and then click **Options**. The **PowerPoint Options** window opens and the content of the **General** tab is displayed. The author's name must match the **User name** in this tab. - -The following is the complete sample code in both C\# and Visual Basic. - -### [C#](#tab/cs) -[!code-csharp[](../../samples/presentation/delete_all_the_comments_by_an_author_from_all_the_slides_a_presentatio/cs/Program.cs)] - -### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/presentation/delete_all_the_comments_by_an_author_from_all_the_slides_a_presentatio/vb/Program.vb)] - -## See also - - - -- [Open XML SDK class library reference](/office/open-xml/open-xml-sdk) diff --git a/docs/presentation/how-to-delete-all-the-comments-by-an-author-from-all-the-slides-in-a-presentation.md b/docs/presentation/how-to-delete-all-the-comments-by-an-author-from-all-the-slides-in-a-presentation.md new file mode 100644 index 00000000..1613e2a0 --- /dev/null +++ b/docs/presentation/how-to-delete-all-the-comments-by-an-author-from-all-the-slides-in-a-presentation.md @@ -0,0 +1,131 @@ +--- + +api_name: +- Microsoft.Office.DocumentFormat.OpenXML.Packaging +api_type: +- schema +ms.assetid: 3b892a6a-2972-461e-94a9-0a1ede854bda +title: 'Delete all the comments by an author from all the slides in a presentation' +ms.suite: office + +ms.author: o365devx +author: o365devx +ms.topic: conceptual +ms.date: 12/30/2024 +ms.localizationpriority: medium +--- +# Delete all the comments by an author from all the slides in a presentation + +This topic shows how to use the classes in the Open XML SDK for +Office to delete all of the comments by a specific author in a +presentation programmatically. + +> [!NOTE] +> This sample is for PowerPoint modern comments. For classic comments view +> the [archived sample on GitHub](https://github.com/OfficeDev/open-xml-docs/blob/7002d692ab4abc629d617ef6a0214fc2bf2910c8/docs/how-to-delete-all-the-comments-by-an-author-from-all-the-slides-in-a-presentatio.md). + + + + + +## Getting a PresentationDocument Object + +In the Open XML SDK, the class represents a +presentation document package. To work with a presentation document, +first create an instance of the `PresentationDocument` class, and then work with +that instance. To create the class instance from the document call the + method that uses a +file path, and a Boolean value as the second parameter to specify +whether a document is editable. To open a document for read/write, +specify the value `true` for this parameter +as shown in the following `using` statement. +In this code, the *fileName* parameter is a string that represents the +path for the file from which you want to open the document, and the +author is the user name displayed in the General tab of the PowerPoint +Options. + +### [C#](#tab/cs-1) +[!code-csharp[](../../samples/presentation/delete_all_the_comments_by_an_author_from_all_the_slides_a_presentatio/cs/Program.cs#snippet1)] + +### [Visual Basic](#tab/vb-1) +[!code-vb[](../../samples/presentation/delete_all_the_comments_by_an_author_from_all_the_slides_a_presentatio/vb/Program.vb#snippet1)] +*** + + +[!include[Using Statement](../includes/presentation/using-statement.md)] `doc`. + +[!include[Structure](../includes/presentation/structure.md)] + +## The Structure of the Comment Element + +The following text from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification +introduces comments in a presentation package. + +> A comment is a text note attached to a slide, with the primary purpose +> of allowing readers of a presentation to provide feedback to the +> presentation author. Each comment contains an unformatted text string +> and information about its author, and is attached to a particular +> location on a slide. Comments can be visible while editing the +> presentation, but do not appear when a slide show is given. The +> displaying application decides when to display comments and determines +> their visual appearance. +> +> © [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] + +[!include[description of a comment](../includes/presentation/modern-comment-description.md)] + +## How the Sample Code Works + +After opening the presentation document for read/write access and +instantiating the `PresentationDocument` +class, the code gets the specified comment author from the list of +comment authors. + +### [C#](#tab/cs-2) +[!code-csharp[](../../samples/presentation/delete_all_the_comments_by_an_author_from_all_the_slides_a_presentatio/cs/Program.cs#snippet2)] + +### [Visual Basic](#tab/vb-2) +[!code-vb[](../../samples/presentation/delete_all_the_comments_by_an_author_from_all_the_slides_a_presentatio/vb/Program.vb#snippet2)] +*** + + +By iterating through the matching authors and all the slides in the +presentation the code gets all the slide parts, and the comments part of +each slide part. It then gets the list of comments by the specified +author and deletes each one. It also verifies that the comment part has +no existing comment, in which case it deletes that part. It also deletes +the comment author from the comment authors part. + +### [C#](#tab/cs-3) +[!code-csharp[](../../samples/presentation/delete_all_the_comments_by_an_author_from_all_the_slides_a_presentatio/cs/Program.cs#snippet3)] + +### [Visual Basic](#tab/vb-3) +[!code-vb[](../../samples/presentation/delete_all_the_comments_by_an_author_from_all_the_slides_a_presentatio/vb/Program.vb#snippet3)] +*** + + +## Sample Code + +The following method takes as parameters the source presentation file +name and path and the name of the comment author whose comments are to +be deleted. It finds all the comments by the specified author in the +presentation and deletes them. It then deletes the comment author from +the list of comment authors. + +> [!NOTE] +> To get the exact author's name, open the presentation file and click the **File** menu item, and then click **Options**. The **PowerPoint Options** window opens and the content of the **General** tab is displayed. The author's name must match the **User name** in this tab. + +The following is the complete sample code in both C\# and Visual Basic. + +### [C#](#tab/cs) +[!code-csharp[](../../samples/presentation/delete_all_the_comments_by_an_author_from_all_the_slides_a_presentatio/cs/Program.cs#snippet0)] + +### [Visual Basic](#tab/vb) +[!code-vb[](../../samples/presentation/delete_all_the_comments_by_an_author_from_all_the_slides_a_presentatio/vb/Program.vb#snippet0)] +*** + +## See also + + + +- [Open XML SDK class library reference](/office/open-xml/open-xml-sdk) diff --git a/docs/presentation/how-to-get-all-the-external-hyperlinks-in-a-presentation.md b/docs/presentation/how-to-get-all-the-external-hyperlinks-in-a-presentation.md index 097d24a4..60210e84 100644 --- a/docs/presentation/how-to-get-all-the-external-hyperlinks-in-a-presentation.md +++ b/docs/presentation/how-to-get-all-the-external-hyperlinks-in-a-presentation.md @@ -11,7 +11,7 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 12/06/2024 ms.localizationpriority: medium --- # Get all the external hyperlinks in a presentation @@ -24,46 +24,30 @@ programmatically. -------------------------------------------------------------------------------- ## Getting a PresentationDocument Object -In the Open XML SDK, the [PresentationDocument](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationdocument.aspx) class represents a +In the Open XML SDK, the class represents a presentation document package. To work with a presentation document, -first create an instance of the **PresentationDocument** class, and then work with +first create an instance of the `PresentationDocument` class, and then work with that instance. To create the class instance from the document call the -[PresentationDocument.Open(String, Boolean)](https://msdn.microsoft.com/library/office/cc562287.aspx) + method that uses a file path, and a Boolean value as the second parameter to specify whether a document is editable. Set this second -parameter to **false** to open the file for -read-only access, or **true** if you want to +parameter to `false` to open the file for +read-only access, or `true` if you want to open the file for read/write access. In this topic, it is best to open the file for read-only access to protect the file against accidental -writing. The following **using** statement -opens the file for read-only access. In this code segment, the **fileName** parameter is a string that represents the +writing. The following `using` statement +opens the file for read-only access. In this code segment, the `fileName` parameter is a string that represents the path for the file from which you want to open the document. -### [C#](#tab/cs-0) -```csharp - // Open the presentation file as read-only. - using (PresentationDocument document = PresentationDocument.Open(fileName, false)) - { - // Insert other code here. - } -``` +### [C#](#tab/cs-1) +[!code-csharp[](../../samples/presentation/get_all_the_external_hyperlinks/cs/Program.cs#snippet1)] -### [Visual Basic](#tab/vb-0) -```vb - ' Open the presentation file as read-only. - Using document As PresentationDocument = PresentationDocument.Open(fileName, False) - ' Insert other code here. - End Using -``` +### [Visual Basic](#tab/vb-1) +[!code-vb[](../../samples/presentation/get_all_the_external_hyperlinks/vb/Program.vb#snippet1)] *** -The **using** statement provides a recommended -alternative to the typical .Open, .Save, .Close sequence. It ensures -that the **Dispose** method (internal method -used by the Open XML SDK to clean up resources) is automatically called -when the closing brace is reached. The block that follows the **using** statement establishes a scope for the -object that is created or named in the **using** statement, in this case **document**. +[!include[Using Statement](../includes/presentation/using-statement.md)] `document`. -------------------------------------------------------------------------------- @@ -74,21 +58,19 @@ object that is created or named in the **using** statement, in this case **docum ## Structure of the Hyperlink Element In this how-to code example, you are going to work with external hyperlinks. Therefore, it is best to familiarize yourself with the -hyperlink element. The following text from the [ISO/IEC -29500](https://www.iso.org/standard/71691.html) specification -introduces the **id** (Hyperlink Target). +hyperlink element. The following text from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification +introduces the `id` (Hyperlink Target). > Specifies the ID of the relationship whose target shall be used as the > target for thishyperlink. -> +> > If this attribute is omitted, then there shall be no external > hyperlink target for the current hyperlink - a location in the current > document can still be target via the anchor attribute. If this > attribute exists, it shall supersede the value in the anchor > attribute. -> -> [*Example*: Consider the following class="keyword">PresentationML** fragment for a hyperlink: +> +> [*Example*: Consider the following `PresentationML` fragment for a hyperlink: ```xml @@ -98,7 +80,7 @@ introduces the **id** (Hyperlink Target). ``` -> The **id** attribute value of **rId9** specifies that relationship in the +> The `id` attribute value of `rId9` specifies that relationship in the > associated relationship part item with a corresponding Id attribute > value must be navigated to when this hyperlink is invoked. For > example, if the following XML is present in the associated @@ -106,19 +88,18 @@ introduces the **id** (Hyperlink Target). ```xml - + ``` > The target of this hyperlink would therefore be the target of -> relationship **rId9** - in this case, +> relationship `rId9` - in this case, > https://www.example.com. *end example*] -> +> > The possible values for this attribute are defined by the > ST\_RelationshipId simple type(§22.8.2.1). -> -> © ISO/IEC29500: 2008. +> +> © [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] -------------------------------------------------------------------------------- @@ -129,79 +110,37 @@ all the slides in the presentation and returns a list of strings that represent the Universal Resource Identifiers (URIs) of all the external hyperlinks in the presentation. -### [C#](#tab/cs-1) -```csharp - // Iterate through all the slide parts in the presentation part. - foreach (SlidePart slidePart in document.PresentationPart.SlideParts) - { - IEnumerable links = slidePart.Slide.Descendants(); - - // Iterate through all the links in the slide part. - foreach (Drawing.HyperlinkType link in links) - { - - // Iterate through all the external relationships in the slide part. - foreach (HyperlinkRelationship relation in slidePart.HyperlinkRelationships) - { - // If the relationship ID matches the link ID… - if (relation.Id.Equals(link.Id)) - { - // Add the URI of the external relationship to the list of strings. - ret.Add(relation.Uri.AbsoluteUri); - - } -``` +### [C#](#tab/cs-2) +[!code-csharp[](../../samples/presentation/get_all_the_external_hyperlinks/cs/Program.cs#snippet2)] -### [Visual Basic](#tab/vb-1) -```vb - ' Iterate through all the slide parts in the presentation part. - For Each slidePart As SlidePart In document.PresentationPart.SlideParts - Dim links As IEnumerable(Of Drawing.HyperlinkType) = slidePart.Slide.Descendants(Of Drawing.HyperlinkType)() - - ' Iterate through all the links in the slide part. - For Each link As Drawing.HyperlinkType In links - - ' Iterate through all the external relationships in the slide part. - For Each relation As HyperlinkRelationship In slidePart.HyperlinkRelationships - ' If the relationship ID matches the link ID… - If relation.Id.Equals(link.Id) Then - ' Add the URI of the external relationship to the list of strings. - ret.Add(relation.Uri.AbsoluteUri) - End If -``` +### [Visual Basic](#tab/vb-2) +[!code-vb[](../../samples/presentation/get_all_the_external_hyperlinks/vb/Program.vb#snippet2)] *** -------------------------------------------------------------------------------- ## Sample Code + Following is the complete code sample that you can use to return the list of all external links in a presentation. You can use the following -loop in your program to call the **GetAllExternalHyperlinksInPresentation** method to +loop in your program to call the `GetAllExternalHyperlinksInPresentation` method to get the list of URIs in your presentation. -### [C#](#tab/cs-2) -```csharp - string fileName = @"C:\Users\Public\Documents\Myppt7.pptx"; - foreach (string s in GetAllExternalHyperlinksInPresentation(fileName)) - Console.WriteLine(s); -``` +### [C#](#tab/cs-3) +[!code-csharp[](../../samples/presentation/get_all_the_external_hyperlinks/cs/Program.cs#snippet3)] -### [Visual Basic](#tab/vb-2) -```vb - Dim fileName As String - fileName = "C:\Users\Public\Documents\Myppt7.pptx" - For Each s As String In GetAllExternalHyperlinksInPresentation(fileName) - Console.WriteLine(s) - Next -``` +### [Visual Basic](#tab/vb-3) +[!code-vb[](../../samples/presentation/get_all_the_external_hyperlinks/vb/Program.vb#snippet3)] *** +Following is the complete sample code in both C\# and Visual Basic. ### [C#](#tab/cs) -[!code-csharp[](../../samples/presentation/get_all_the_external_hyperlinks/cs/Program.cs)] +[!code-csharp[](../../samples/presentation/get_all_the_external_hyperlinks/cs/Program.cs#snippet)] ### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/presentation/get_all_the_external_hyperlinks/vb/Program.vb)] +[!code-vb[](../../samples/presentation/get_all_the_external_hyperlinks/vb/Program.vb#snippet)] +*** -------------------------------------------------------------------------------- ## See also diff --git a/docs/presentation/how-to-get-all-the-text-in-a-slide-in-a-presentation.md b/docs/presentation/how-to-get-all-the-text-in-a-slide-in-a-presentation.md index bc2893bc..5a1ae012 100644 --- a/docs/presentation/how-to-get-all-the-text-in-a-slide-in-a-presentation.md +++ b/docs/presentation/how-to-get-all-the-text-in-a-slide-in-a-presentation.md @@ -11,7 +11,7 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 12/06/2024 ms.localizationpriority: medium --- # Get all the text in a slide in a presentation @@ -24,44 +24,29 @@ programmatically. -------------------------------------------------------------------------------- ## Getting a PresentationDocument object -In the Open XML SDK, the [PresentationDocument](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationdocument.aspx) class represents a +In the Open XML SDK, the class represents a presentation document package. To work with a presentation document, -first create an instance of the **PresentationDocument** class, and then work with +first create an instance of the `PresentationDocument` class, and then work with that instance. To create the class instance from the document call the -[PresentationDocument.Open(String, Boolean)](https://msdn.microsoft.com/library/office/cc562287.aspx) + method that uses a file path, and a Boolean value as the second parameter to specify whether a document is editable. To open a document -for read/write access, assign the value **true** to this parameter; for read-only access -assign it the value **false** as shown in the -following **using** statement. In this code, -the **file** parameter is a string that +for read/write access, assign the value `true` to this parameter; for read-only access +assign it the value `false` as shown in the +following `using` statement. In this code, +the `file` parameter is a string that represents the path for the file from which you want to open the document. -### [C#](#tab/cs-0) -```csharp - // Open the presentation as read-only. - using (PresentationDocument presentationDocument = PresentationDocument.Open(presentationFile, false)) - { - // Insert other code here. - } -``` - -### [Visual Basic](#tab/vb-0) -```vb - Using presentationDocument As PresentationDocument = PresentationDocument.Open(file, False) - ' Insert other code here. - End Using -``` +### [C#](#tab/cs-1) +[!code-csharp[](../../samples/presentation/get_all_the_text_a_slide/cs/Program.cs#snippet1)] + +### [Visual Basic](#tab/vb-1) +[!code-vb[](../../samples/presentation/get_all_the_text_a_slide/vb/Program.vb#snippet1)] *** -The **using** statement provides a recommended -alternative to the typical .Open, .Save, .Close sequence. It ensures -that the **Dispose** method (internal method -used by the Open XML SDK to clean up resources) is automatically called -when the closing brace is reached. The block that follows the **using** statement establishes a scope for the -object that is created or named in the **using** statement, in this case **presentationDocument**. +[!include[Using Statement](../includes/presentation/using-statement.md)] `presentationDocument`. -------------------------------------------------------------------------------- @@ -69,42 +54,19 @@ object that is created or named in the **using** statement, in this case **prese [!include[Structure](../includes/presentation/structure.md)] ## How the Sample Code Works -The sample code consists of three overloads of the **GetAllTextInSlide** method. In the following + +The sample code consists of three overloads of the `GetAllTextInSlide` method. In the following segment, the first overloaded method opens the source presentation that contains the slide with text to get, and passes the presentation to the second overloaded method, which gets the slide part. This method returns the array of strings that the second method returns to it, each of which represents a paragraph of text in the specified slide. -### [C#](#tab/cs-1) -```csharp - // Get all the text in a slide. - public static string[] GetAllTextInSlide(string presentationFile, int slideIndex) - { - // Open the presentation as read-only. - using (PresentationDocument presentationDocument = PresentationDocument.Open(presentationFile, false)) - { - // Pass the presentation and the slide index - // to the next GetAllTextInSlide method, and - // then return the array of strings it returns. - return GetAllTextInSlide(presentationDocument, slideIndex); - } - } -``` +### [C#](#tab/cs-2) +[!code-csharp[](../../samples/presentation/get_all_the_text_a_slide/cs/Program.cs#snippet2)] -### [Visual Basic](#tab/vb-1) -```vb - ' Get all the text in a slide. - Public Shared Function GetAllTextInSlide(ByVal presentationFile As String, ByVal slideIndex As Integer) As String() - ' Open the presentation as read-only. - Using presentationDocument As PresentationDocument = PresentationDocument.Open(presentationFile, False) - ' Pass the presentation and the slide index - ' to the next GetAllTextInSlide method, and - ' then return the array of strings it returns. - Return GetAllTextInSlide(presentationDocument, slideIndex) - End Using - End Function -``` +### [Visual Basic](#tab/vb-2) +[!code-vb[](../../samples/presentation/get_all_the_text_a_slide/vb/Program.vb#snippet2)] *** @@ -114,239 +76,57 @@ to the first overloaded method the array of strings that the third overloaded method returns to it, each of which represents a paragraph of text in the specified slide. -### [C#](#tab/cs-2) -```csharp - public static string[] GetAllTextInSlide(PresentationDocument presentationDocument, int slideIndex) - { - // Verify that the presentation document exists. - if (presentationDocument == null) - { - throw new ArgumentNullException("presentationDocument"); - } - - // Verify that the slide index is not out of range. - if (slideIndex < 0) - { - throw new ArgumentOutOfRangeException("slideIndex"); - } - - // Get the presentation part of the presentation document. - PresentationPart presentationPart = presentationDocument.PresentationPart; - - // Verify that the presentation part and presentation exist. - if (presentationPart != null && presentationPart.Presentation != null) - { - // Get the Presentation object from the presentation part. - Presentation presentation = presentationPart.Presentation; - - // Verify that the slide ID list exists. - if (presentation.SlideIdList != null) - { - // Get the collection of slide IDs from the slide ID list. - var slideIds = presentation.SlideIdList.ChildElements; - - // If the slide ID is in range... - if (slideIndex < slideIds.Count) - { - // Get the relationship ID of the slide. - string slidePartRelationshipId = (slideIds[slideIndex] as SlideId).RelationshipId; - - // Get the specified slide part from the relationship ID. - SlidePart slidePart = (SlidePart)presentationPart.GetPartById(slidePartRelationshipId); - - // Pass the slide part to the next method, and - // then return the array of strings that method - // returns to the previous method. - return GetAllTextInSlide(slidePart); - } - } - } - // Else, return null. - return null; - } -``` +### [C#](#tab/cs-3) +[!code-csharp[](../../samples/presentation/get_all_the_text_a_slide/cs/Program.cs#snippet3)] -### [Visual Basic](#tab/vb-2) -```vb - Public Shared Function GetAllTextInSlide(ByVal presentationDocument As PresentationDocument, ByVal slideIndex As Integer) As String() - ' Verify that the presentation document exists. - If presentationDocument Is Nothing Then - Throw New ArgumentNullException("presentationDocument") - End If - - ' Verify that the slide index is not out of range. - If slideIndex < 0 Then - Throw New ArgumentOutOfRangeException("slideIndex") - End If - - ' Get the presentation part of the presentation document. - Dim presentationPart As PresentationPart = presentationDocument.PresentationPart - - ' Verify that the presentation part and presentation exist. - If presentationPart IsNot Nothing AndAlso presentationPart.Presentation IsNot Nothing Then - ' Get the Presentation object from the presentation part. - Dim presentation As Presentation = presentationPart.Presentation - - ' Verify that the slide ID list exists. - If presentation.SlideIdList IsNot Nothing Then - ' Get the collection of slide IDs from the slide ID list. - Dim slideIds = presentation.SlideIdList.ChildElements - - ' If the slide ID is in range... - If slideIndex < slideIds.Count Then - ' Get the relationship ID of the slide. - Dim slidePartRelationshipId As String = (TryCast(slideIds(slideIndex), SlideId)).RelationshipId - - ' Get the specified slide part from the relationship ID. - Dim slidePart As SlidePart = CType(presentationPart.GetPartById(slidePartRelationshipId), SlidePart) - - ' Pass the slide part to the next method, and - ' then return the array of strings that method - ' returns to the previous method. - Return GetAllTextInSlide(slidePart) - End If - End If - End If - - ' Else, return null. - Return Nothing - End Function -``` +### [Visual Basic](#tab/vb-3) +[!code-vb[](../../samples/presentation/get_all_the_text_a_slide/vb/Program.vb#snippet3)] *** - The following code segment shows the third overloaded method, which takes takes the slide part passed in, and returns to the second overloaded method a string array of text paragraphs. It starts by verifying that the slide part passed in exists, and then it creates a linked list of strings. It iterates through the paragraphs in the slide -passed in, and using a **StringBuilder** object +passed in, and using a `StringBuilder` object to concatenate all the lines of text in a paragraph, it assigns each paragraph to a string in the linked list. It then returns to the second overloaded method an array of strings that represents all the text in the specified slide in the presentation. -### [C#](#tab/cs-3) -```csharp - public static string[] GetAllTextInSlide(SlidePart slidePart) - { - // Verify that the slide part exists. - if (slidePart == null) - { - throw new ArgumentNullException("slidePart"); - } - - // Create a new linked list of strings. - LinkedList texts = new LinkedList(); - - // If the slide exists... - if (slidePart.Slide != null) - { - // Iterate through all the paragraphs in the slide. - foreach (var paragraph in slidePart.Slide.Descendants()) - { - // Create a new string builder. - StringBuilder paragraphText = new StringBuilder(); - - // Iterate through the lines of the paragraph. - foreach (var text in paragraph.Descendants()) - { - // Append each line to the previous lines. - paragraphText.Append(text.Text); - } - - if (paragraphText.Length > 0) - { - // Add each paragraph to the linked list. - texts.AddLast(paragraphText.ToString()); - } - } - } - - if (texts.Count > 0) - { - // Return an array of strings. - return texts.ToArray(); - } - else - { - return null; - } - } -``` +### [C#](#tab/cs-4) +[!code-csharp[](../../samples/presentation/get_all_the_text_a_slide/cs/Program.cs#snippet4)] -### [Visual Basic](#tab/vb-3) -```vb - Public Shared Function GetAllTextInSlide(ByVal slidePart As SlidePart) As String() - ' Verify that the slide part exists. - If slidePart Is Nothing Then - Throw New ArgumentNullException("slidePart") - End If - - ' Create a new linked list of strings. - Dim texts As New LinkedList(Of String)() - - ' If the slide exists... - If slidePart.Slide IsNot Nothing Then - ' Iterate through all the paragraphs in the slide. - For Each paragraph In slidePart.Slide.Descendants(Of DocumentFormat.OpenXml.Drawing.Paragraph)() - ' Create a new string builder. - Dim paragraphText As New StringBuilder() - - ' Iterate through the lines of the paragraph. - For Each text In paragraph.Descendants(Of DocumentFormat.OpenXml.Drawing.Text)() - ' Append each line to the previous lines. - paragraphText.Append(text.Text) - Next text - - If paragraphText.Length > 0 Then - ' Add each paragraph to the linked list. - texts.AddLast(paragraphText.ToString()) - End If - Next paragraph - End If - - If texts.Count > 0 Then - ' Return an array of strings. - Return texts.ToArray() - Else - Return Nothing - End If - End Function -``` +### [Visual Basic](#tab/vb-4) +[!code-vb[](../../samples/presentation/get_all_the_text_a_slide/vb/Program.vb#snippet4)] *** + -------------------------------------------------------------------------------- ## Sample Code + Following is the complete sample code that you can use to get all the text in a specific slide in a presentation file. For example, you can -use the following **foreach** loop in your -program to get the array of strings returned by the method **GetAllTextInSlide**, which represents the text in -the second slide of the presentation file "Myppt8.pptx." +use the following `foreach` loop in your +program to get the array of strings returned by the method `GetAllTextInSlide`, which represents the text in +the slide at the index of `slideIndex` of the presentation file found at the `filePath`. -### [C#](#tab/cs-4) -```csharp - foreach (string s in GetAllTextInSlide(@"C:\Users\Public\Documents\Myppt8.pptx", 1)) - Console.WriteLine(s); -``` +### [C#](#tab/cs-5) +[!code-csharp[](../../samples/presentation/get_all_the_text_a_slide/cs/Program.cs#snippet5)] -### [Visual Basic](#tab/vb-4) -```vb - For Each s As String In GetAllTextInSlide("C:\Users\Public\Documents\Myppt8.pptx", 1) - Console.WriteLine(s) - Next -``` +### [Visual Basic](#tab/vb-5) +[!code-vb[](../../samples/presentation/get_all_the_text_a_slide/vb/Program.vb#snippet5)] *** Following is the complete sample code in both C\# and Visual Basic. ### [C#](#tab/cs) -[!code-csharp[](../../samples/presentation/get_all_the_text_a_slide/cs/Program.cs)] +[!code-csharp[](../../samples/presentation/get_all_the_text_a_slide/cs/Program.cs#snippet)] ### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/presentation/get_all_the_text_a_slide/vb/Program.vb)] +[!code-vb[](../../samples/presentation/get_all_the_text_a_slide/vb/Program.vb#snippet)] -------------------------------------------------------------------------------- ## See also diff --git a/docs/presentation/how-to-get-all-the-text-in-all-slides-in-a-presentation.md b/docs/presentation/how-to-get-all-the-text-in-all-slides-in-a-presentation.md index e9131cea..5b168982 100644 --- a/docs/presentation/how-to-get-all-the-text-in-all-slides-in-a-presentation.md +++ b/docs/presentation/how-to-get-all-the-text-in-all-slides-in-a-presentation.md @@ -11,7 +11,7 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 12/04/2024 ms.localizationpriority: medium --- # Get all the text in all slides in a presentation @@ -24,44 +24,29 @@ all of the text in all of the slides in a presentation programmatically. -------------------------------------------------------------------------------- ## Getting a PresentationDocument object -In the Open XML SDK, the [PresentationDocument](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationdocument.aspx) class represents a +In the Open XML SDK, the class represents a presentation document package. To work with a presentation document, -first create an instance of the **PresentationDocument** class, and then work with +first create an instance of the `PresentationDocument` class, and then work with that instance. To create the class instance from the document call the -[PresentationDocument.Open(String, Boolean)](https://msdn.microsoft.com/library/office/cc562287.aspx) + method that uses a file path, and a Boolean value as the second parameter to specify whether a document is editable. To open a document -for read/write access, assign the value **true** to this parameter; for read-only access -assign it the value **false** as shown in the -following **using** statement. In this code, -the **presentationFile** parameter is a string +for read/write access, assign the value `true` to this parameter; for read-only access +assign it the value `false` as shown in the +following `using` statement. In this code, +the `presentationFile` parameter is a string that represents the path for the file from which you want to open the document. -### [C#](#tab/cs-0) -```csharp - // Open the presentation as read-only. - using (PresentationDocument presentationDocument = PresentationDocument.Open(presentationFile, false)) - { - // Insert other code here. - } -``` - -### [Visual Basic](#tab/vb-0) -```vb - Using presentationDocument As PresentationDocument = PresentationDocument.Open(presentationFile, False) - ' Insert other code here. - End Using -``` +### [C#](#tab/cs-1) +[!code-csharp[](../../samples/presentation/get_all_the_text_all_slides/cs/Program.cs#snippet1)] + +### [Visual Basic](#tab/vb-1) +[!code-vb[](../../samples/presentation/get_all_the_text_all_slides/vb/Program.vb#snippet1)] *** -The **using** statement provides a recommended -alternative to the typical .Open, .Save, .Close sequence. It ensures -that the **Dispose** method (internal method -used by the Open XML SDK to clean up resources) is automatically called -when the closing brace is reached. The block that follows the **using** statement establishes a scope for the -object that is created or named in the **using** statement, in this case **presentationDocument**. +[!include[Using Statement](../includes/presentation/using-statement.md)] `presentationDocument`. -------------------------------------------------------------------------------- @@ -70,55 +55,29 @@ object that is created or named in the **using** statement, in this case **prese ## Sample Code The following code gets all the text in all the slides in a specific -presentation file. For example, you can enter the name of the -presentation file from the keyboard, and then use a **foreach** loop in your program to get the array of -strings returned by the method **GetSlideIdAndText** as shown in the following +presentation file. For example, you can pass the name of the file as an argument, +and then use a `foreach` loop in your program to get the array of +strings returned by the method `GetSlideIdAndText` as shown in the following example. -### [C#](#tab/cs-1) -```csharp - Console.Write("Please enter a presentation file name without extension: "); - string fileName = Console.ReadLine(); - string file = @"C:\Users\Public\Documents\" + fileName + ".pptx"; - int numberOfSlides = CountSlides(file); - System.Console.WriteLine("Number of slides = {0}", numberOfSlides); - string slideText; - for (int i = 0; i < numberOfSlides; i++) - { - GetSlideIdAndText(out slideText, file, i); - System.Console.WriteLine("Slide #{0} contains: {1}", i + 1, slideText); - } - System.Console.ReadKey(); -``` +### [C#](#tab/cs-2) +[!code-csharp[](../../samples/presentation/get_all_the_text_all_slides/cs/Program.cs#snippet2)] -### [Visual Basic](#tab/vb-1) -```vb - Console.Write("Please enter a presentation file name without extension: ") - Dim fileName As String = System.Console.ReadLine() - Dim file As String = "C:\Users\Public\Documents\" + fileName + ".pptx" - Dim numberOfSlides As Integer = CountSlides(file) - System.Console.WriteLine("Number of slides = {0}", numberOfSlides) - Dim slideText As String = Nothing - For i As Integer = 0 To numberOfSlides - 1 - GetSlideIdAndText(slideText, file, i) - System.Console.WriteLine("Slide #{0} contains: {1}", i + 1, slideText) - Next - System.Console.ReadKey() -``` +### [Visual Basic](#tab/vb-2) +[!code-vb[](../../samples/presentation/get_all_the_text_all_slides/vb/Program.vb#snippet2)] *** - The following is the complete sample code in both C\# and Visual Basic. ### [C#](#tab/cs) -[!code-csharp[](../../samples/presentation/get_all_the_text_all_slides/cs/Program.cs)] +[!code-csharp[](../../samples/presentation/get_all_the_text_all_slides/cs/Program.cs#snippet)] ### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/presentation/get_all_the_text_all_slides/vb/Program.vb)] +[!code-vb[](../../samples/presentation/get_all_the_text_all_slides/vb/Program.vb#snippet)] +*** -------------------------------------------------------------------------------- ## See also -[Open XML SDK class library -reference](https://msdn.microsoft.com/library/36c8a76e-ce1b-5959-7e85-5d77db7f46d6(Office.15).aspx) +[Open XML SDK class library reference](/office/open-xml/open-xml-sdk) diff --git a/docs/presentation/how-to-get-the-titles-of-all-the-slides-in-a-presentation.md b/docs/presentation/how-to-get-the-titles-of-all-the-slides-in-a-presentation.md index fcad0560..15916510 100644 --- a/docs/presentation/how-to-get-the-titles-of-all-the-slides-in-a-presentation.md +++ b/docs/presentation/how-to-get-the-titles-of-all-the-slides-in-a-presentation.md @@ -11,7 +11,7 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 12/04/2024 ms.localizationpriority: medium --- # Get the titles of all the slides in a presentation @@ -25,66 +25,44 @@ programmatically. --------------------------------------------------------------------------------- ## Getting a PresentationDocument Object -In the Open XML SDK, the **[PresentationDocument](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationdocument.aspx)** class represents a +In the Open XML SDK, the class represents a presentation document package. To work with a presentation document, -first create an instance of the **PresentationDocument** class, and then work with +first create an instance of the `PresentationDocument` class, and then work with that instance. To create the class instance from the document call the -**[PresentationDocument.Open(String, Boolean)](https://msdn.microsoft.com/library/office/cc562287.aspx)** + method that uses a file path, and a Boolean value as the second parameter to specify whether a document is editable. To open a document -for read-only, specify the value **false** for -this parameter as shown in the following **using** statement. In this code, the **presentationFile** parameter is a string that +for read-only, specify the value `false` for +this parameter as shown in the following `using` statement. In this code, the `presentationFile` parameter is a string that represents the path for the file from which you want to open the document. -### [C#](#tab/cs-0) -```csharp - // Open the presentation as read-only. - using (PresentationDocument presentationDocument = PresentationDocument.Open(presentationFile, false)) - { - // Insert other code here. - } -``` - -### [Visual Basic](#tab/vb-0) -```vb - ' Open the presentation as read-only. - Using presentationDocument As PresentationDocument = PresentationDocument.Open(presentationFile, False) - ' Insert other code here. - End Using -``` +### [C#](#tab/cs-1) +[!code-csharp[](../../samples/presentation/get_the_titles_of_all_the_slides/cs/Program.cs#snippet1)] + +### [Visual Basic](#tab/vb-1) +[!code-vb[](../../samples/presentation/get_the_titles_of_all_the_slides/vb/Program.vb#snippet1)] *** -The **using** statement provides a recommended -alternative to the typical .Open, .Save, .Close sequence. It ensures -that the **Dispose** method (internal method -used by the Open XML SDK to clean up resources) is automatically called -when the closing brace is reached. The block that follows the **using** statement establishes a scope for the -object that is created or named in the **using** statement, in this case -*presentationDocument*. +[!include[Using Statement](../includes/presentation/using-statement.md)] `presentationDocument`. + [!include[Structure](../includes/presentation/structure.md)] ## Sample Code -The following is the complete sample code that you can use to get the +The following sample code gets all the titles of the slides in a presentation file. For example you can use the -following **foreach** statement in your program -to return all the titles in the presentation file, "Myppt9.pptx." +following `foreach` statement in your program +to return all the titles in the presentation file located at +the first argument. -### [C#](#tab/cs-1) -```csharp - foreach (string s in GetSlideTitles(@"C:\Users\Public\Documents\Myppt9.pptx")) - Console.WriteLine(s); -``` +### [C#](#tab/cs-2) +[!code-csharp[](../../samples/presentation/get_the_titles_of_all_the_slides/cs/Program.cs#snippet2)] -### [Visual Basic](#tab/vb-1) -```vb - For Each s As String In GetSlideTitles("C:\Users\Public\Documents\Myppt9.pptx") - Console.WriteLine(s) - Next -``` +### [Visual Basic](#tab/vb-2) +[!code-vb[](../../samples/presentation/get_the_titles_of_all_the_slides/vb/Program.vb#snippet2)] *** @@ -94,10 +72,11 @@ the presentation, each on a separate line. Following is the complete sample code in both C\# and Visual Basic. ### [C#](#tab/cs) -[!code-csharp[](../../samples/presentation/get_the_titles_of_all_the_slides/cs/Program.cs)] +[!code-csharp[](../../samples/presentation/get_the_titles_of_all_the_slides/cs/Program.cs#snippet)] ### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/presentation/get_the_titles_of_all_the_slides/vb/Program.vb)] +[!code-vb[](../../samples/presentation/get_the_titles_of_all_the_slides/vb/Program.vb#snippet)] +*** -------------------------------------------------------------------------------- ## See also @@ -105,4 +84,4 @@ Following is the complete sample code in both C\# and Visual Basic. [Open XML SDK class library -reference](https://msdn.microsoft.com/library/36c8a76e-ce1b-5959-7e85-5d77db7f46d6(Office.15).aspx) +reference](/office/open-xml/open-xml-sdk) diff --git a/docs/presentation/how-to-insert-a-new-slide-into-a-presentation.md b/docs/presentation/how-to-insert-a-new-slide-into-a-presentation.md index 04dc8770..b307498f 100644 --- a/docs/presentation/how-to-insert-a-new-slide-into-a-presentation.md +++ b/docs/presentation/how-to-insert-a-new-slide-into-a-presentation.md @@ -11,7 +11,7 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 12/03/2024 ms.localizationpriority: high --- # Insert a new slide into a presentation @@ -23,75 +23,103 @@ insert a new slide into a presentation programmatically. ## Getting a PresentationDocument Object -In the Open XML SDK, the [PresentationDocument](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationdocument.aspx) class represents a +In the Open XML SDK, the class represents a presentation document package. To work with a presentation document, -first create an instance of the **PresentationDocument** class, and then work with -that instance. To create the class instance from the document call the [Open(String, Boolean)](https://msdn.microsoft.com/library/office/cc562287.aspx) method that uses a +first create an instance of the `PresentationDocument` class, and then work with +that instance. To create the class instance from the document call the method that uses a file path, and a Boolean value as the second parameter to specify whether a document is editable. To open a document for read/write, -specify the value **true** for this parameter -as shown in the following **using** statement. -In this code segment, the *presentationFile* parameter is a string that +specify the value `true` for this parameter +as shown in the following `using` statement. +In this code segment, the `presentationFile` parameter is a string that represents the full path for the file from which you want to open the document. -### [C#](#tab/cs-0) -```csharp - using (PresentationDocument presentationDocument = PresentationDocument.Open(presentationFile, true)) - { - // Insert other code here. - } -``` - -### [Visual Basic](#tab/vb-0) -```vb - Using presentationDocument As PresentationDocument = PresentationDocument.Open(presentationFile, True) - ' Insert other code here. - End Using -``` +### [C#](#tab/cs-1) +[!code-csharp[](../../samples/presentation/insert_a_new_slideto/cs/Program.cs#snippet1)] + +### [Visual Basic](#tab/vb-1) +[!code-vb[](../../samples/presentation/insert_a_new_slideto/vb/Program.vb#snippet1)] *** -The **using** statement provides a recommended -alternative to the typical .Open, .Save, .Close sequence. It ensures -that the **Dispose** method (internal method -used by the Open XML SDK to clean up resources) is automatically called -when the closing brace is reached. The block that follows the **using** statement establishes a scope for the -object that is created or named in the **using** statement, in this case -*presentationDocument*. +[!include[Using Statement](../includes/presentation/using-statement.md)] `presentationDocument`. [!include[Structure](../includes/presentation/structure.md)] -## Sample Code +## How the Sample Code Works -By using the sample code you can add a new slide to an existing -presentation. In your program, you can use the following call to the -**InsertNewSlide** method to add a new slide to -a presentation file named "Myppt10.pptx," with the title "My new slide," -at position 1. +The sample code consists of two overloads of the `InsertNewSlide` method. The first overloaded +method takes three parameters: the full path to the presentation file to +which to add a slide, an integer that represents the zero-based slide +index position in the presentation where to add the slide, and the +string that represents the title of the new slide. It opens the +presentation file as read/write, gets a `PresentationDocument` object, and then passes that +object to the second overloaded `InsertNewSlide` method, which performs the +insertion. -### [C#](#tab/cs-1) -```csharp - InsertNewSlide(@"C:\Users\Public\Documents\Myppt10.pptx", 1, "My new slide"); -``` +### [C#](#tab/cs-10) +[!code-csharp[](../../samples/presentation/insert_a_new_slideto/cs/Program.cs#snippet10)] -### [Visual Basic](#tab/vb-1) -```vb - InsertNewSlide("C:\Users\Public\Documents\Myppt10.pptx", 1, "My new slide") -``` +### [Visual Basic](#tab/vb-10) +[!code-vb[](../../samples/presentation/insert_a_new_slideto/vb/Program.vb#snippet10)] +*** + +The second overloaded `InsertNewSlide` method +creates a new `Slide` object, sets its +properties, and then inserts it into the slide order in the +presentation. The first section of the method creates the slide and sets +its properties. + +### [C#](#tab/cs-11) +[!code-csharp[](../../samples/presentation/insert_a_new_slideto/cs/Program.cs#snippet11)] + +### [Visual Basic](#tab/vb-11) +[!code-vb[](../../samples/presentation/insert_a_new_slideto/vb/Program.vb#snippet11)] +*** + +The next section of the second overloaded `InsertNewSlide` method adds a title shape to the +slide and sets its properties, including its text. + +### [C#](#tab/cs-12) +[!code-csharp[](../../samples/presentation/insert_a_new_slideto/cs/Program.cs#snippet12)] + +### [Visual Basic](#tab/vb-12) +[!code-vb[](../../samples/presentation/insert_a_new_slideto/vb/Program.vb#snippet12)] +*** + +The next section of the second overloaded `InsertNewSlide` method adds a body shape to the +slide and sets its properties, including its text. + +### [C#](#tab/cs-13) +[!code-csharp[](../../samples/presentation/insert_a_new_slideto/cs/Program.cs#snippet13)] + +### [Visual Basic](#tab/vb-13) +[!code-vb[](../../samples/presentation/insert_a_new_slideto/vb/Program.vb#snippet13)] *** +The final section of the second overloaded `InsertNewSlide` method creates a new slide part, +finds the specified index position where to insert the slide, and then +inserts it and assigns the new slide to the new slide part. -After you have run the program, the new slide would show up as the -second slide in the presentation. +### [C#](#tab/cs-14) +[!code-csharp[](../../samples/presentation/insert_a_new_slideto/cs/Program.cs#snippet14)] + +### [Visual Basic](#tab/vb-14) +[!code-vb[](../../samples/presentation/insert_a_new_slideto/vb/Program.vb#snippet14)] +*** + + +## Sample Code The following is the complete sample code in both C\# and Visual Basic. ### [C#](#tab/cs) -[!code-csharp[](../../samples/presentation/insert_a_new_slideto/cs/Program.cs)] +[!code-csharp[](../../samples/presentation/insert_a_new_slideto/cs/Program.cs#snippet0)] ### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/presentation/insert_a_new_slideto/vb/Program.vb)] +[!code-vb[](../../samples/presentation/insert_a_new_slideto/vb/Program.vb#snippet0)] +*** ## See also diff --git a/docs/presentation/how-to-move-a-paragraph-from-one-presentation-to-another.md b/docs/presentation/how-to-move-a-paragraph-from-one-presentation-to-another.md index 05214688..cb3d60f0 100644 --- a/docs/presentation/how-to-move-a-paragraph-from-one-presentation-to-another.md +++ b/docs/presentation/how-to-move-a-paragraph-from-one-presentation-to-another.md @@ -11,7 +11,7 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 12/02/2024 ms.localizationpriority: medium --- # Move a paragraph from one presentation to another @@ -24,47 +24,33 @@ programmatically. ## Getting a PresentationDocument Object -In the Open XML SDK, the [PresentationDocument](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationdocument.aspx) class represents a +In the Open XML SDK, the class represents a presentation document package. To work with a presentation document, -first create an instance of the **PresentationDocument** class, and then work with +first create an instance of the `PresentationDocument` class, and then work with that instance. To create the class instance from the document call the -[Open(String, Boolean)](https://msdn.microsoft.com/library/office/cc562287.aspx) method that uses a + method that uses a file path, and a Boolean value as the second parameter to specify whether a document is editable. To open a document for read/write, -specify the value **true** for this parameter -as shown in the following **using** statement. -In this code, the *file* parameter is a string that represents the path +specify the value `true` for this parameter +as shown in the following `using` statement. +In this code, the `sourceFile` parameter is a string that represents the path for the file from which you want to open the document. -### [C#](#tab/cs-0) -```csharp - using (PresentationDocument doc = PresentationDocument.Open(file, true)) - { - // Insert other code here. - } -``` +### [C#](#tab/cs-1) +[!code-csharp[](../../samples/presentation/move_a_paragraph_from_one_presentation_to_another/cs/Program.cs#snippet1)] -### [Visual Basic](#tab/vb-0) -```vb - Using doc As PresentationDocument = PresentationDocument.Open(file, True) - ' Insert other code here. - End Using -``` +### [Visual Basic](#tab/vb-1) +[!code-vb[](../../samples/presentation/move_a_paragraph_from_one_presentation_to_another/vb/Program.vb#snippet1)] *** -The **using** statement provides a recommended -alternative to the typical .Open, .Save, .Close sequence. It ensures -that the **Dispose** method (internal method -used by the Open XML SDK to clean up resources) is automatically called -when the closing brace is reached. The block that follows the **using** statement establishes a scope for the -object that is created or named in the **using** statement, in this case *doc*. +[!include[Using Statement](../includes/presentation/using-statement.md)] `sourceDoc`. [!include[Structure](../includes/presentation/structure.md)] ## Structure of the Shape Text Body -The following text from the [ISO/IEC 29500](https://www.iso.org/standard/71691.html) specification +The following text from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification introduces the structure of this element. > This element specifies the existence of text to be contained within @@ -72,7 +58,7 @@ introduces the structure of this element. > properties are contained within this element. There can be multiple > paragraphs and within paragraphs multiple runs of text. > -> © ISO/IEC29500: 2008. +> © [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] The following table lists the child elements of the shape text body and the description of each. @@ -97,194 +83,52 @@ The following XML Schema fragment defines the contents of this element: ## How the Sample Code Works -The code in this topic consists of two methods, **MoveParagraphToPresentation** and **GetFirstSlide**. The first method takes two string +The code in this topic consists of two methods, `MoveParagraphToPresentation` and `GetFirstSlide`. The first method takes two string parameters: one that represents the source file, which contains the paragraph to move, and one that represents the target file, to which the paragraph is moved. The method opens both presentation files and then -calls the **GetFirstSlide** method to get the -first slide in each file. It then gets the first **TextBody** shape in each slide and the first -paragraph in the source shape. It performs a **deep -clone** of the source paragraph, copying not only the source **Paragraph** object itself, but also everything +calls the `GetFirstSlide` method to get the +first slide in each file. It then gets the first `TextBody` shape in each slide and the first +paragraph in the source shape. It performs a `deep clone` of the source paragraph, +copying not only the source `Paragraph` object itself, but also everything contained in that object, including its text. It then inserts the cloned paragraph in the target file and removes the source paragraph from the source file, replacing it with a placeholder paragraph. Finally, it saves the modified slides in both presentations. -### [C#](#tab/cs-1) -```csharp - // Moves a paragraph range in a TextBody shape in the source document - // to another TextBody shape in the target document. - public static void MoveParagraphToPresentation(string sourceFile, string targetFile) - { - // Open the source file as read/write. - using (PresentationDocument sourceDoc = PresentationDocument.Open(sourceFile, true)) - { - // Open the target file as read/write. - using (PresentationDocument targetDoc = PresentationDocument.Open(targetFile, true)) - { - // Get the first slide in the source presentation. - SlidePart slide1 = GetFirstSlide(sourceDoc); - - // Get the first TextBody shape in it. - TextBody textBody1 = slide1.Slide.Descendants().First(); - - // Get the first paragraph in the TextBody shape. - // Note: "Drawing" is the alias of namespace DocumentFormat.OpenXml.Drawing - Drawing.Paragraph p1 = textBody1.Elements().First(); - - // Get the first slide in the target presentation. - SlidePart slide2 = GetFirstSlide(targetDoc); - - // Get the first TextBody shape in it. - TextBody textBody2 = slide2.Slide.Descendants().First(); - - // Clone the source paragraph and insert the cloned. paragraph into the target TextBody shape. - // Passing "true" creates a deep clone, which creates a copy of the - // Paragraph object and everything directly or indirectly referenced by that object. - textBody2.Append(p1.CloneNode(true)); - - // Remove the source paragraph from the source file. - textBody1.RemoveChild(p1); - - // Replace the removed paragraph with a placeholder. - textBody1.AppendChild(new Drawing.Paragraph()); - - // Save the slide in the source file. - slide1.Slide.Save(); - - // Save the slide in the target file. - slide2.Slide.Save(); - } - } - } -``` +### [C#](#tab/cs-2) +[!code-csharp[](../../samples/presentation/move_a_paragraph_from_one_presentation_to_another/cs/Program.cs#snippet2)] -### [Visual Basic](#tab/vb-1) -```vb - ' Moves a paragraph range in a TextBody shape in the source document - ' to another TextBody shape in the target document. - Public Shared Sub MoveParagraphToPresentation(ByVal sourceFile As String, ByVal targetFile As String) - ' Open the source file as read/write. - Using sourceDoc As PresentationDocument = PresentationDocument.Open(sourceFile, True) - ' Open the target file as read/write. - Using targetDoc As PresentationDocument = PresentationDocument.Open(targetFile, True) - ' Get the first slide in the source presentation. - Dim slide1 As SlidePart = GetFirstSlide(sourceDoc) - - ' Get the first TextBody shape in it. - Dim textBody1 As TextBody = slide1.Slide.Descendants(Of TextBody)().First() - - ' Get the first paragraph in the TextBody shape. - ' Note: "Drawing" is the alias of namespace DocumentFormat.OpenXml.Drawing - Dim p1 As Drawing.Paragraph = textBody1.Elements(Of Drawing.Paragraph)().First() - - ' Get the first slide in the target presentation. - Dim slide2 As SlidePart = GetFirstSlide(targetDoc) - - ' Get the first TextBody shape in it. - Dim textBody2 As TextBody = slide2.Slide.Descendants(Of TextBody)().First() - - ' Clone the source paragraph and insert the cloned. paragraph into the target TextBody shape. - ' Passing "true" creates a deep clone, which creates a copy of the - ' Paragraph object and everything directly or indirectly referenced by that object. - textBody2.Append(p1.CloneNode(True)) - - ' Remove the source paragraph from the source file. - textBody1.RemoveChild(Of Drawing.Paragraph)(p1) - - ' Replace the removed paragraph with a placeholder. - textBody1.AppendChild(Of Drawing.Paragraph)(New Drawing.Paragraph()) - - ' Save the slide in the source file. - slide1.Slide.Save() - - ' Save the slide in the target file. - slide2.Slide.Save() - End Using - End Using - End Sub -``` +### [Visual Basic](#tab/vb-2) +[!code-vb[](../../samples/presentation/move_a_paragraph_from_one_presentation_to_another/vb/Program.vb#snippet2)] *** -The **GetFirstSlide** method takes the **PresentationDocument** object passed in, gets its +The `GetFirstSlide` method takes the `PresentationDocument` object passed in, gets its presentation part, and then gets the ID of the first slide in its slide list. It then gets the relationship ID of the slide, gets the slide part from the relationship ID, and returns the slide part to the calling method. -### [C#](#tab/cs-2) -```csharp - // Get the slide part of the first slide in the presentation document. - public static SlidePart GetFirstSlide(PresentationDocument presentationDocument) - { - // Get relationship ID of the first slide - PresentationPart part = presentationDocument.PresentationPart; - SlideId slideId = part.Presentation.SlideIdList.GetFirstChild(); - string relId = slideId.RelationshipId; - - // Get the slide part by the relationship ID. - SlidePart slidePart = (SlidePart)part.GetPartById(relId); - - return slidePart; - } -``` - -### [Visual Basic](#tab/vb-2) -```vb - ' Get the slide part of the first slide in the presentation document. - Public Shared Function GetFirstSlide(ByVal presentationDocument As PresentationDocument) As SlidePart - ' Get relationship ID of the first slide - Dim part As PresentationPart = presentationDocument.PresentationPart - Dim slideId As SlideId = part.Presentation.SlideIdList.GetFirstChild(Of SlideId)() - Dim relId As String = slideId.RelationshipId - - ' Get the slide part by the relationship ID. - Dim slidePart As SlidePart = CType(part.GetPartById(relId), SlidePart) - - Return slidePart - End Function -``` -*** - - -## Sample Code - -By using this sample code, you can move a paragraph from one -presentation to another. In your program, you can use the following call -to the **MoveParagraphToPresentation** method -to move the first paragraph from the presentation file "Myppt4.pptx" to -the presentation file "Myppt12.pptx". - ### [C#](#tab/cs-3) -```csharp - string sourceFile = @"C:\Users\Public\Documents\Myppt4.pptx"; - string targetFile = @"C:\Users\Public\Documents\Myppt12.pptx"; - MoveParagraphToPresentation(sourceFile, targetFile); -``` +[!code-csharp[](../../samples/presentation/move_a_paragraph_from_one_presentation_to_another/cs/Program.cs#snippet3)] ### [Visual Basic](#tab/vb-3) -```vb - Dim sourceFile As String = "C:\Users\Public\Documents\Myppt4.pptx" - Dim targetFile As String = "C:\Users\Public\Documents\Myppt12.pptx" - MoveParagraphToPresentation(sourceFile, targetFile) -``` +[!code-vb[](../../samples/presentation/move_a_paragraph_from_one_presentation_to_another/vb/Program.vb#snippet3)] *** -After you run the program take a look on the content of both the source -and the target files to see the moved paragraph. +## Sample Code The following is the complete sample code in both C\# and Visual Basic. ### [C#](#tab/cs) -[!code-csharp[](../../samples/presentation/move_a_paragraph_from_one_presentation_to_another/cs/Program.cs)] +[!code-csharp[](../../samples/presentation/move_a_paragraph_from_one_presentation_to_another/cs/Program.cs#snippet)] ### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/presentation/move_a_paragraph_from_one_presentation_to_another/vb/Program.vb)] +[!code-vb[](../../samples/presentation/move_a_paragraph_from_one_presentation_to_another/vb/Program.vb#snippet)] +*** ## See also - - - [Open XML SDK class library reference](/office/open-xml/open-xml-sdk) diff --git a/docs/presentation/how-to-move-a-slide-to-a-new-position-in-a-presentation.md b/docs/presentation/how-to-move-a-slide-to-a-new-position-in-a-presentation.md index 142b1f0e..d8c70637 100644 --- a/docs/presentation/how-to-move-a-slide-to-a-new-position-in-a-presentation.md +++ b/docs/presentation/how-to-move-a-slide-to-a-new-position-in-a-presentation.md @@ -11,7 +11,7 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 12/02/2024 ms.localizationpriority: medium --- # Move a slide to a new position in a presentation @@ -24,46 +24,31 @@ programmatically. -------------------------------------------------------------------------------- ## Getting a Presentation Object -In the Open XML SDK, the [PresentationDocument](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationdocument.aspx) class represents a + +In the Open XML SDK, the class represents a presentation document package. To work with a presentation document, -first create an instance of the **PresentationDocument** class, and then work with +first create an instance of the `PresentationDocument` class, and then work with that instance. To create the class instance from the document call the -[Open(String, Boolean)](https://msdn.microsoft.com/library/office/cc562287.aspx) method that uses a + method that uses a file path, and a Boolean value as the second parameter to specify whether a document is editable. In order to count the number of slides in a presentation, it is best to open the file for read-only access in order to avoid accidental writing to the file. To do that, specify the -value **false** for the Boolean parameter as -shown in the following **using** statement. In -this code, the **presentationFile** parameter +value `false` for the Boolean parameter as +shown in the following `using` statement. In +this code, the `presentationFile` parameter is a string that represents the path for the file from which you want to open the document. ### [C#](#tab/cs-0) -```csharp - // Open the presentation as read-only. - using (PresentationDocument presentationDocument = PresentationDocument.Open(presentationFile, false)) - { - // Insert other code here. - } -``` +[!code-csharp[](../../samples/presentation/move_a_slide_to_a_new_position/cs/Program.cs#snippet1)] ### [Visual Basic](#tab/vb-0) -```vb - ' Open the presentation as read-only. - Using presentationDocument As PresentationDocument = PresentationDocument.Open(presentationFile, False) - ' Insert other code here. - End Using -``` +[!code-vb[](../../samples/presentation/move_a_slide_to_a_new_position/vb/Program.vb#snippet1)] *** -The **using** statement provides a recommended -alternative to the typical .Open, .Save, .Close sequence. It ensures -that the **Dispose** method (internal method -used by the Open XML SDK to clean up resources) is automatically called -when the closing brace is reached. The block that follows the **using** statement establishes a scope for the -object that is created or named in the **using** statement, in this case **presentationDocument**. +[!include[Using Statement](../includes/presentation/using-statement.md)] `presentationDocument`. -------------------------------------------------------------------------------- @@ -71,6 +56,7 @@ object that is created or named in the **using** statement, in this case **prese [!include[Structure](../includes/presentation/structure.md)] ## How the Sample Code Works + In order to move a specific slide in a presentation file to a new position, you need to know first the number of slides in the presentation. Therefore, the code in this topic is divided into two @@ -79,300 +65,118 @@ moving a slide to a new position. -------------------------------------------------------------------------------- + ## Counting the Number of Slides + The sample code for counting the number of slides consists of two -overloads of the method **CountSlides**. The -first overload uses a **string** parameter and -the second overload uses a **PresentationDocument** parameter. In the first -**CountSlides** method, the sample code opens -the presentation document in the **using** -statement. Then it passes the **PresentationDocument** object to the second **CountSlides** method, which returns an integer +overloads of the method `CountSlides`. The +first overload uses a `string` parameter and +the second overload uses a `PresentationDocument` parameter. In the first +`CountSlides` method, the sample code opens +the presentation document in the `using` +statement. Then it passes the `PresentationDocument` object to the second `CountSlides` method, which returns an integer number that represents the number of slides in the presentation. ### [C#](#tab/cs-1) -```csharp - // Pass the presentation to the next CountSlides method - // and return the slide count. - return CountSlides(presentationDocument); -``` +[!code-csharp[](../../samples/presentation/move_a_slide_to_a_new_position/cs/Program.cs#snippet2)] ### [Visual Basic](#tab/vb-1) -```vb - ' Pass the presentation to the next CountSlides method - ' and return the slide count. - Return CountSlides(presentationDocument) -``` +[!code-vb[](../../samples/presentation/move_a_slide_to_a_new_position/vb/Program.vb#snippet2)] *** -In the second **CountSlides** method, the code -verifies that the **PresentationDocument** -object passed in is not **null**, and if it is -not, it gets a **PresentationPart** object from -the **PresentationDocument** object. By using -the **SlideParts** the code gets the **slideCount** and returns it. +In the second `CountSlides` method, the code +verifies that the `PresentationDocument` +object passed in is not `null`, and if it is +not, it gets a `PresentationPart` object from +the `PresentationDocument` object. By using +the `SlideParts` the code gets the `slideCount` and returns it. ### [C#](#tab/cs-2) -```csharp - // Check for a null document object. - if (presentationDocument == null) - { - throw new ArgumentNullException("presentationDocument"); - } - - int slidesCount = 0; - - // Get the presentation part of document. - PresentationPart presentationPart = presentationDocument.PresentationPart; - - // Get the slide count from the SlideParts. - if (presentationPart != null) - { - slidesCount = presentationPart.SlideParts.Count(); - } - // Return the slide count to the previous method. - return slidesCount; -``` +[!code-csharp[](../../samples/presentation/move_a_slide_to_a_new_position/cs/Program.cs#snippet3)] ### [Visual Basic](#tab/vb-2) -```vb - ' Check for a null document object. - If presentationDocument Is Nothing Then - Throw New ArgumentNullException("presentationDocument") - End If - - Dim slidesCount As Integer = 0 - - ' Get the presentation part of document. - Dim presentationPart As PresentationPart = presentationDocument.PresentationPart - - ' Get the slide count from the SlideParts. - If presentationPart IsNot Nothing Then - slidesCount = presentationPart.SlideParts.Count() - End If - ' Return the slide count to the previous method. - Return slidesCount -``` +[!code-vb[](../../samples/presentation/move_a_slide_to_a_new_position/vb/Program.vb#snippet3)] *** -------------------------------------------------------------------------------- + ## Moving a Slide from one Position to Another + Moving a slide to a new position requires opening the file for -read/write access by specifying the value **true** to the Boolean parameter as shown in the -following **using** statement. The code for -moving a slide consists of two overloads of the **MoveSlide** method. The first overloaded **MoveSlide** method takes three parameters: a string +read/write access by specifying the value `true` to the Boolean parameter as shown in the +following `using` statement. The code for +moving a slide consists of two overloads of the `MoveSlide` method. The first overloaded `MoveSlide` method takes three parameters: a string that represents the presentation file name and path and two integers that represent the current index position of the slide and the index position to which to move the slide respectively. It opens the -presentation file, gets a **PresentationDocument** object, and then passes that -object and the two integers, *from* and *to*, to the second overloaded -**MoveSlide** method, which performs the actual +presentation file, gets a `PresentationDocument` object, and then passes that +object and the two integers, `from` and `to`, to the second overloaded +`MoveSlide` method, which performs the actual move. ### [C#](#tab/cs-3) -```csharp - // Move a slide to a different position in the slide order in the presentation. - public static void MoveSlide(string presentationFile, int from, int to) - { - using (PresentationDocument presentationDocument = PresentationDocument.Open(presentationFile, true)) - { - MoveSlide(presentationDocument, from, to); - } - } -``` +[!code-csharp[](../../samples/presentation/move_a_slide_to_a_new_position/cs/Program.cs#snippet4)] ### [Visual Basic](#tab/vb-3) -```vb - ' Move a slide to a different position in the slide order in the presentation. - Public Shared Sub MoveSlide(ByVal presentationFile As String, ByVal [from] As Integer, ByVal [to] As Integer) - Using presentationDocument As PresentationDocument = PresentationDocument.Open(presentationFile, True) - MoveSlide(presentationDocument, From, [to]) - End Using - End Sub -``` +[!code-vb[](../../samples/presentation/move_a_slide_to_a_new_position/vb/Program.vb#snippet4)] *** -In the second overloaded **MoveSlide** method, -the **CountSlides** method is called to get the +In the second overloaded `MoveSlide` method, +the `CountSlides` method is called to get the number of slides in the presentation. The code then checks if the -zero-based indexes, *from* and *to*, are within the range and different +zero-based indexes, `from` and `to`, are within the range and different from one another. ### [C#](#tab/cs-4) -```csharp - public static void MoveSlide(PresentationDocument presentationDocument, int from, int to) - { - if (presentationDocument == null) - { - throw new ArgumentNullException("presentationDocument"); - } - - // Call the CountSlides method to get the number of slides in the presentation. - int slidesCount = CountSlides(presentationDocument); - - // Verify that both from and to positions are within range and different from one another. - if (from < 0 || from >= slidesCount) - { - throw new ArgumentOutOfRangeException("from"); - } - - if (to < 0 || from >= slidesCount || to == from) - { - throw new ArgumentOutOfRangeException("to"); - } -``` +[!code-csharp[](../../samples/presentation/move_a_slide_to_a_new_position/cs/Program.cs#snippet5)] ### [Visual Basic](#tab/vb-4) -```vb - Public Shared Sub MoveSlide(ByVal presentationDocument As PresentationDocument, ByVal [from] As Integer, ByVal [to] As Integer) - If presentationDocument Is Nothing Then - Throw New ArgumentNullException("presentationDocument") - End If - - ' Call the CountSlides method to get the number of slides in the presentation. - Dim slidesCount As Integer = CountSlides(presentationDocument) - - ' Verify that both from and to positions are within range and different from one another. - If - From < 0 OrElse - From >= slidesCount Then - Throw New ArgumentOutOfRangeException("from") - End If - - If [to] < 0 OrElse - From >= slidesCount OrElse [to] = - From Then - Throw New ArgumentOutOfRangeException("to") - End If -``` +[!code-vb[](../../samples/presentation/move_a_slide_to_a_new_position/vb/Program.vb#snippet5)] *** -A **PresentationPart** object is declared and -set equal to the presentation part of the **PresentationDocument** object passed in. The **PresentationPart** object is used to create a **Presentation** object, and then create a **SlideIdList** object that represents the list of -slides in the presentation from the **Presentation** object. A slide ID of the source +A `PresentationPart` object is declared and +set equal to the presentation part of the `PresentationDocument` object passed in. The `PresentationPart` object is used to create a `Presentation` object, and then create a `SlideIdList` object that represents the list of +slides in the presentation from the `Presentation` object. A slide ID of the source slide (the slide to move) is obtained, and then the position of the target slide (the slide after which in the slide order to move the source slide) is identified. ### [C#](#tab/cs-5) -```csharp - // Get the presentation part from the presentation document. - PresentationPart presentationPart = presentationDocument.PresentationPart; - - // The slide count is not zero, so the presentation must contain slides. - Presentation presentation = presentationPart.Presentation; - SlideIdList slideIdList = presentation.SlideIdList; - - // Get the slide ID of the source slide. - SlideId sourceSlide = slideIdList.ChildElements[from] as SlideId; - - SlideId targetSlide = null; - - // Identify the position of the target slide after which to move the source slide. - if (to == 0) - { - targetSlide = null; - } - else if (from < to) - { - targetSlide = slideIdList.ChildElements[to] as SlideId; - } - else - { - targetSlide = slideIdList.ChildElements[to - 1] as SlideId; - } -``` +[!code-csharp[](../../samples/presentation/move_a_slide_to_a_new_position/cs/Program.cs#snippet6)] ### [Visual Basic](#tab/vb-5) -```vb - ' Get the presentation part from the presentation document. - Dim presentationPart As PresentationPart = presentationDocument.PresentationPart - - ' The slide count is not zero, so the presentation must contain slides. - Dim presentation As Presentation = presentationPart.Presentation - Dim slideIdList As SlideIdList = presentation.SlideIdList - - ' Get the slide ID of the source slide. - Dim sourceSlide As SlideId = TryCast(slideIdList.ChildElements(From), SlideId) - - Dim targetSlide As SlideId = Nothing - - ' Identify the position of the target slide after which to move the source slide. - If to = 0 Then - targetSlide = Nothing - ElseIf From < to Then - targetSlide = TryCast(slideIdList.ChildElements(to), SlideId) - Else - targetSlide = TryCast(slideIdList.ChildElements(to - 1), SlideId) - End If -``` +[!code-vb[](../../samples/presentation/move_a_slide_to_a_new_position/vb/Program.vb#snippet6)] *** -The **Remove** method of the **SlideID** object is used to remove the source slide -from its current position, and then the **InsertAfter** method of the **SlideIdList** object is used to insert the source +The `Remove` method of the `SlideID` object is used to remove the source slide +from its current position, and then the `InsertAfter` method of the `SlideIdList` object is used to insert the source slide in the index position after the target slide. Finally, the modified presentation is saved. ### [C#](#tab/cs-6) -```csharp - // Remove the source slide from its current position. - sourceSlide.Remove(); - - // Insert the source slide at its new position after the target slide. - slideIdList.InsertAfter(sourceSlide, targetSlide); - - // Save the modified presentation. - presentation.Save(); -``` +[!code-csharp[](../../samples/presentation/move_a_slide_to_a_new_position/cs/Program.cs#snippet7)] ### [Visual Basic](#tab/vb-6) -```vb - ' Remove the source slide from its current position. - sourceSlide.Remove() - - ' Insert the source slide at its new position after the target slide. - slideIdList.InsertAfter(sourceSlide, targetSlide) - - ' Save the modified presentation. - presentation.Save() -``` +[!code-vb[](../../samples/presentation/move_a_slide_to_a_new_position/vb/Program.vb#snippet7)] *** -------------------------------------------------------------------------------- ## Sample Code Following is the complete sample code that you can use to move a slide -from one position to another in the same presentation file. For -instance, you can use the following call in your program to move a slide -from position 0 to position 1 in a presentation file named -"Myppt11.pptx". - -### [C#](#tab/cs-7) -```csharp - MoveSlide(@"C:\Users\Public\Documents\Myppt11.pptx", 0, 1); -``` - -### [Visual Basic](#tab/vb-7) -```vb - MoveSlide("C:\Users\Public\Documents\Myppt11.pptx", 0, 1) -``` -*** - - -After you run the program, check your presentation file to see the new -positions of the slides. - -Following is the complete sample code in both C\# and Visual Basic. +from one position to another in the same presentation file in both C\# and Visual Basic. ### [C#](#tab/cs) -[!code-csharp[](../../samples/presentation/move_a_slide_to_a_new_position/cs/Program.cs)] +[!code-csharp[](../../samples/presentation/move_a_slide_to_a_new_position/cs/Program.cs#snippet0)] ### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/presentation/move_a_slide_to_a_new_position/vb/Program.vb)] +[!code-vb[](../../samples/presentation/move_a_slide_to_a_new_position/vb/Program.vb#snippet0)] +*** -------------------------------------------------------------------------------- ## See also diff --git a/docs/presentation/how-to-open-a-presentation-document-for-read-only-access.md b/docs/presentation/how-to-open-a-presentation-document-for-read-only-access.md index c704cde9..7c75d558 100644 --- a/docs/presentation/how-to-open-a-presentation-document-for-read-only-access.md +++ b/docs/presentation/how-to-open-a-presentation-document-for-read-only-access.md @@ -11,7 +11,7 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 11/27/2024 ms.localizationpriority: medium --- # Open a presentation document for read-only access @@ -35,37 +35,37 @@ document. ## Create an Instance of the PresentationDocument Class -In the Open XML SDK, the [PresentationDocument](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationdocument.aspx) class represents a +In the Open XML SDK, the class represents a presentation document package. To work with a presentation document, -first create an instance of the **PresentationDocument** class, and then work with +first create an instance of the `PresentationDocument` class, and then work with that instance. To create the class instance from the document call one -of the [Open](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationdocument.open.aspx) methods. Several Open methods are +of the methods. Several Open methods are provided, each with a different signature. The following table contains -a subset of the overloads for the **Open** +a subset of the overloads for the `Open` method that you can use to open the package. | Name | Description | |---|---| -| [Open(String, Boolean)](https://msdn.microsoft.com/library/office/cc562287.aspx) | Create a new instance of the **PresentationDocument** class from the specified file. | -| [Open(Stream, Boolean)](https://msdn.microsoft.com/library/office/cc536282.aspx) | Create a new instance of the **PresentationDocument** class from the I/O stream. | -| [Open(Package)](https://msdn.microsoft.com/library/office/cc514901.aspx) | Create a new instance of the **PresentationDocument** class from the specified package. | +| | Create a new instance of the `PresentationDocument` class from the specified file. | +| | Create a new instance of the `PresentationDocument` class from the I/O stream. | +| | Create a new instance of the `PresentationDocument` class from the specified package. | -The previous table includes two **Open** +The previous table includes two `Open` methods that accept a Boolean value as the second parameter to specify whether a document is editable. To open a document for read-only access, -specify the value **false** for this parameter. +specify the value `false` for this parameter. For example, you can open the presentation file as read-only and assign -it to a [PresentationDocument](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationdocument.aspx) object as shown in the -following **using** statement. In this code, -the **presentationFile** parameter is a string +it to a object as shown in the +following `using` statement. In this code, +the `presentationFile` parameter is a string that represents the path of the file from which you want to open the document. ### [C#](#tab/cs-0) ```csharp - using (PresentationDocument presentationDocument = PresentationDocument.Open(presentationFile, false)) + using (PresentationDocument presentationDocument = PresentationDocument.Open(presentationFilePath, false)) { // Insert other code here. } @@ -73,15 +73,15 @@ document. ### [Visual Basic](#tab/vb-0) ```vb - Using presentationDocument As PresentationDocument = PresentationDocument.Open(presentationFile, False) + Using presentationDocument As PresentationDocument = PresentationDocument.Open(presentationFilePath, False) ' Insert other code here. End Using ``` *** -You can also use the second overload of the **Open** method, in the table above, to create an -instance of the **PresentationDocument** class +You can also use the second overload of the `Open` method, in the table above, to create an +instance of the `PresentationDocument` class based on an I/O stream. You might use this approach if you have a Microsoft SharePoint Foundation 2010 application that uses stream I/O and you want to use the Open XML SDK to work with a document. The @@ -90,8 +90,7 @@ following code segment opens a document based on a stream. ### [C#](#tab/cs-1) ```csharp Stream stream = File.Open(strDoc, FileMode.Open); - using (PresentationDocument presentationDocument = - PresentationDocument.Open(stream, false)) + using (PresentationDocument presentationDocument = PresentationDocument.Open(stream, false)) { // Place other code here. } @@ -108,21 +107,20 @@ following code segment opens a document based on a stream. Suppose you have an application that employs the Open XML support in the -**System.IO.Packaging** namespace of the .NET +`System.IO.Packaging` namespace of the .NET Framework Class Library, and you want to use the Open XML SDK to work with a package read-only. The Open XML SDK includes a method -overload that accepts a **Package** as the only +overload that accepts a `Package` as the only parameter. There is no Boolean parameter to indicate whether the document should be opened for editing. The recommended approach is to open the package as read-only prior to creating the instance of the -**PresentationDocument** class. The following +`PresentationDocument` class. The following code segment performs this operation. ### [C#](#tab/cs-2) ```csharp Package presentationPackage = Package.Open(filepath, FileMode.Open, FileAccess.Read); - using (PresentationDocument presentationDocument = - PresentationDocument.Open(presentationPackage)) + using (PresentationDocument presentationDocument = PresentationDocument.Open(presentationPackage)) { // Other code goes here. } @@ -143,68 +141,29 @@ code segment performs this operation. ## How the Sample Code Works In the sample code, after you open the presentation document in the -**using** statement for read-only access, -instantiate the **PresentationPart**, and open +`using` statement for read-only access, +instantiate the `PresentationPart`, and open the slide list. Then you get the relationship ID of the first slide. ### [C#](#tab/cs-3) -```csharp - // Get the relationship ID of the first slide. - PresentationPart part = ppt.PresentationPart; - OpenXmlElementList slideIds = part.Presentation.SlideIdList.ChildElements; - string relId = (slideIds[index] as SlideId).RelationshipId; -``` - +[!code-csharp[](../../samples/presentation/open_for_read_only_access/cs/Program.cs#snippet2)] ### [Visual Basic](#tab/vb-3) -```vb - ' Get the relationship ID of the first slide. - Dim part As PresentationPart = ppt.PresentationPart - Dim slideIds As OpenXmlElementList = part.Presentation.SlideIdList.ChildElements - Dim relId As String = (TryCast(slideIds(index), SlideId)).RelationshipId -``` +[!code-vb[](../../samples/presentation/open_for_read_only_access/vb/Program.vb#snippet2)] *** -From the relationship ID, **relId**, you get the +From the relationship ID, `relId`, you get the slide part, and then the inner text of the slide by building a text -string using **StringBuilder**. +string using `StringBuilder`. ### [C#](#tab/cs-4) -```csharp - // Get the slide part from the relationship ID. - SlidePart slide = (SlidePart)part.GetPartById(relId); - - // Build a StringBuilder object. - StringBuilder paragraphText = new StringBuilder(); - - // Get the inner text of the slide. - IEnumerable texts = slide.Slide.Descendants(); - foreach (A.Text text in texts) - { - paragraphText.Append(text.Text); - } - sldText = paragraphText.ToString(); -``` - +[!code-csharp[](../../samples/presentation/open_for_read_only_access/cs/Program.cs#snippet3)] ### [Visual Basic](#tab/vb-4) -```vb - ' Get the slide part from the relationship ID. - Dim slide As SlidePart = CType(part.GetPartById(relId), SlidePart) - - ' Build a StringBuilder object. - Dim paragraphText As New StringBuilder() - - ' Get the inner text of the slide. - Dim texts As IEnumerable(Of A.Text) = slide.Slide.Descendants(Of A.Text)() - For Each text As A.Text In texts - paragraphText.Append(text.Text) - Next text - sldText = paragraphText.ToString() -``` +[!code-vb[](../../samples/presentation/open_for_read_only_access/vb/Program.vb#snippet3)] *** -The inner text of the slide, which is an **out** parameter of the **GetSlideIdAndText** method, is passed back to the +The inner text of the slide, which is an `out` parameter of the `GetSlideIdAndText` method, is passed back to the main method to be displayed. > [!IMPORTANT] @@ -214,54 +173,30 @@ main method to be displayed. ## Sample Code The following example opens a presentation file for read-only access and -gets the inner text of a slide at a specified index. To call the method **GetSlideIdAndText** pass in the full path of the -presentation document. Also pass in the **out** -parameter **sldText**, which will be assigned a +gets the inner text of a slide at a specified index. To call the method `GetSlideIdAndText` pass in the full path of the +presentation document. Also pass in the `out` +parameter `sldText`, which will be assigned a value in the method itself, and then you can display its value in the -main program. For example, the following call to the **GetSlideIdAndText** method gets the inner text in -the second slide in a presentation file named "Myppt13.pptx". +main program. For example, the following call to the `GetSlideIdAndText` method gets the inner text in a presentation file +from the index and file path passed to the application as arguments. > [!TIP] -> The most expected exception in this program is the **ArgumentOutOfRangeException** exception. It could be thrown if, for example, you have a file with two slides, and you wanted to display the text in slide number 4. Therefore, it is best to use a **try** block when you call the **GetSlideIdAndText** method as shown in the following example. +> The most expected exception in this program is the `ArgumentOutOfRangeException` exception. It could be thrown if, for example, you have a file with two slides, and you wanted to display the text in slide number 4. Therefore, it is best to use a `try` block when you call the `GetSlideIdAndText` method as shown in the following example. ### [C#](#tab/cs-5) -```csharp - string file = @"C:\Users\Public\Documents\Myppt13.pptx"; - string slideText; - int index = 1; - try - { - GetSlideIdAndText(out slideText, file, index); - Console.WriteLine("The text in the slide #{0} is: {1}", index + 1, slideText); - } - catch (ArgumentOutOfRangeException exp) - { - Console.WriteLine(exp.Message); - } -``` - +[!code-csharp[](../../samples/presentation/open_for_read_only_access/cs/Program.cs#snippet4)] ### [Visual Basic](#tab/vb-5) -```vb - Dim file As String = "C:\Users\Public\Documents\Myppt13.pptx" - Dim slideText As String = Nothing - Dim index As Integer = 1 - Try - GetSlideIdAndText(slideText, file, index) - Console.WriteLine("The text in the slide #{0} is: {1}", index + 1, slideText) - Catch exp As ArgumentOutOfRangeException - Console.WriteLine(exp.Message) - End Try -``` +[!code-vb[](../../samples/presentation/open_for_read_only_access/vb/Program.vb#snippet4)] *** The following is the complete code listing in C\# and Visual Basic. -### [C#](#tab/cs) -[!code-csharp[](../../samples/presentation/open_for_read_only_access/cs/Program.cs)] +### [C#](#tab/cs-6) +[!code-csharp[](../../samples/presentation/open_for_read_only_access/cs/Program.cs#snippet0)] -### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/presentation/open_for_read_only_access/vb/Program.vb)] +### [Visual Basic](#tab/vb-6) +[!code-vb[](../../samples/presentation/open_for_read_only_access/vb/Program.vb#snippet0)] ## See also diff --git a/docs/presentation/how-to-reply-to-a-comment-in-a-presentation.md b/docs/presentation/how-to-reply-to-a-comment-in-a-presentation.md new file mode 100644 index 00000000..9813f31e --- /dev/null +++ b/docs/presentation/how-to-reply-to-a-comment-in-a-presentation.md @@ -0,0 +1,91 @@ +--- + +api_name: +- Microsoft.Office.DocumentFormat.OpenXML.Packaging +api_type: +- schema +ms.assetid: 9774217d-1f71-494a-9ab9-a711661f8e83 +title: 'How to: Reply to a comment in a presentation' +ms.suite: office + +ms.author: o365devx +author: o365devx +ms.topic: conceptual +ms.date: 08/12/2025 +ms.localizationpriority: medium +--- + +# Reply to a comment in a presentation + +This topic shows how to use the classes in the Open XML SDK for +Office to reply to existing comments in a presentation +programmatically. + + +[!include[Structure](../includes/presentation/structure.md)] + +[!include[description of a comment](../includes/presentation/modern-comment-description.md)] + +## How the Sample Code Works + +The sample code opens the presentation document in the using statement. Then it gets or creates the CommentAuthorsPart, and verifies that there is an existing comment authors part. If there is not, it adds one. + +### [C#](#tab/cs-1) +[!code-csharp[](../../samples/presentation/reply_to_comment/cs/Program.cs#snippet1)] + +### [Visual Basic](#tab/vb-1) +[!code-vb[](../../samples/presentation/reply_to_comment/vb/Program.vb#snippet1)] +*** + +Next the code determines if the author that is passed in is on the list of existing authors; if so, it assigns the existing author ID. If not, it adds a new author to the list of authors and assigns an author ID and the parameter values. + +### [C#](#tab/cs-2) +[!code-csharp[](../../samples/presentation/reply_to_comment/cs/Program.cs#snippet2)] + +### [Visual Basic](#tab/vb-2) +[!code-vb[](../../samples/presentation/reply_to_comment/vb/Program.vb#snippet2)] +*** + +Next the code gets the first slide part and verifies that it exists, then checks if there are any comment parts associated with the slide. + +### [C#](#tab/cs-3) +[!code-csharp[](../../samples/presentation/reply_to_comment/cs/Program.cs#snippet3)] + +### [Visual Basic](#tab/vb-3) +[!code-vb[](../../samples/presentation/reply_to_comment/vb/Program.vb#snippet3)] +*** + +The code then retrieves the comment list and then iterates through each comment in the comment list, displays the comment text to the user, and prompts whether they want to reply to each comment. + +### [C#](#tab/cs-5) +[!code-csharp[](../../samples/presentation/reply_to_comment/cs/Program.cs#snippet4)] + +### [Visual Basic](#tab/vb-5) +[!code-vb[](../../samples/presentation/reply_to_comment/vb/Program.vb#snippet4)] +*** + +When the user chooses to reply to a comment, the code prompts for the reply text, then gets or creates a `CommentReplyList` for the comment and adds the new reply with the appropriate author information and timestamp. + +### [C#](#tab/cs-6) +[!code-csharp[](../../samples/presentation/reply_to_comment/cs/Program.cs#snippet5)] + +### [Visual Basic](#tab/vb-6) +[!code-vb[](../../samples/presentation/reply_to_comment/vb/Program.vb#snippet5)] +*** + +## Sample Code + +Following is the complete code sample showing how to reply to existing comments +in a presentation slide with modern PowerPoint comments. + +### [C#](#tab/cs) +[!code-csharp[](../../samples/presentation/reply_to_comment/cs/Program.cs#snippet0)] + +### [Visual Basic](#tab/vb) +[!code-vb[](../../samples/presentation/reply_to_comment/vb/Program.vb#snippet0)] +*** + +## See also + + +- [Open XML SDK class library reference](/office/open-xml/open-xml-sdk) diff --git a/docs/presentation/how-to-retrieve-the-number-of-slides-in-a-presentation-document.md b/docs/presentation/how-to-retrieve-the-number-of-slides-in-a-presentation-document.md index 2afaeeff..04333fb2 100644 --- a/docs/presentation/how-to-retrieve-the-number-of-slides-in-a-presentation-document.md +++ b/docs/presentation/how-to-retrieve-the-number-of-slides-in-a-presentation-document.md @@ -12,7 +12,7 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 06/28/2021 +ms.date: 11/27/2024 ms.localizationpriority: medium --- # Retrieve the number of slides in a presentation document @@ -21,7 +21,7 @@ This topic shows how to use the classes in the Open XML SDK for Office to programmatically retrieve the number of slides in a presentation document, either including hidden slides or not, without loading the document into Microsoft PowerPoint. It contains an example -**RetrieveNumberOfSlides** method to illustrate +`RetrieveNumberOfSlides` method to illustrate this task. @@ -30,24 +30,18 @@ this task. ## RetrieveNumberOfSlides Method -You can use the **RetrieveNumberOfSlides** +You can use the `RetrieveNumberOfSlides` method to get the number of slides in a presentation document, -optionally including the hidden slides. The **RetrieveNumberOfSlides** method accepts two +optionally including the hidden slides. The `RetrieveNumberOfSlides` method accepts two parameters: a string that indicates the path of the file that you want to examine, and an optional Boolean value that indicates whether to include hidden slides in the count. ### [C#](#tab/cs-0) -```csharp - public static int RetrieveNumberOfSlides(string fileName, - bool includeHidden = true) -``` +[!code-csharp[](../../samples/presentation/retrieve_the_number_of_slides/cs/Program.cs#snippet1)] ### [Visual Basic](#tab/vb-0) -```vb - Public Function RetrieveNumberOfSlides(ByVal fileName As String, - Optional ByVal includeHidden As Boolean = True) As Integer -``` +[!code-vb[](../../samples/presentation/retrieve_the_number_of_slides/vb/Program.vb#snippet1)] *** @@ -60,118 +54,66 @@ second parameter value. To call the method, pass all the parameter values, as shown in the following code. ### [C#](#tab/cs-1) -```csharp - // Retrieve the number of slides, excluding the hidden slides. - Console.WriteLine(RetrieveNumberOfSlides(DEMOPATH, false)); - // Retrieve the number of slides, including the hidden slides. - Console.WriteLine(RetrieveNumberOfSlides(DEMOPATH)); -``` +[!code-csharp[](../../samples/presentation/retrieve_the_number_of_slides/cs/Program.cs#snippet2)] ### [Visual Basic](#tab/vb-1) -```vb - ' Retrieve the number of slides, excluding the hidden slides. - Console.WriteLine(RetrieveNumberOfSlides(DEMOPATH, False)) - ' Retrieve the number of slides, including the hidden slides. - Console.WriteLine(RetrieveNumberOfSlides(DEMOPATH)) -``` +[!code-vb[](../../samples/presentation/retrieve_the_number_of_slides/vb/Program.vb#snippet2)] *** + --------------------------------------------------------------------------------- ## How the Code Works -The code starts by creating an integer variable, **slidesCount**, to hold the number of slides. The code then opens the specified presentation by using the [PresentationDocument.Open](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationdocument.open.aspx) method and indicating that the document should be open for read-only access (the -final **false** parameter value). Given the open presentation, the code uses the [PresentationPart](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationdocument.presentationpart.aspx) property to navigate to the main presentation part, storing the reference in a variable named **presentationPart**. +The code starts by creating an integer variable, `slidesCount`, to hold the number of slides. The code then opens the specified presentation by using the method and indicating that the document should be open for read-only access (the +final `false` parameter value). Given the open presentation, the code uses the property to navigate to the main presentation part, storing the reference in a variable named `presentationPart`. -### [C#](#tab/cs-2) -```csharp - using (PresentationDocument doc = - PresentationDocument.Open(fileName, false)) - { - // Get the presentation part of the document. - PresentationPart presentationPart = doc.PresentationPart; - // Code removed here… - } - Return slidesCount; -``` +### [C#](#tab/cs) +[!code-csharp[](../../samples/presentation/retrieve_the_number_of_slides/cs/Program.cs#snippet3)] -### [Visual Basic](#tab/vb-2) -```vb - Using doc As PresentationDocument = - PresentationDocument.Open(fileName, False) - ' Get the presentation part of the document. - Dim presentationPart As PresentationPart = doc.PresentationPart - ' Code removed here… - End Using - Return slidesCount -``` +### [Visual Basic](#tab/vb) +[!code-vb[](../../samples/presentation/retrieve_the_number_of_slides/vb/Program.vb#snippet3)] *** + --------------------------------------------------------------------------------- ## Retrieving the Count of All Slides -If the presentation part reference is not null (and it will not be, for any valid presentation that loads correctly into PowerPoint), the code next calls the **Count** method on the value of the [SlideParts](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationpart.slideparts.aspx) property of the presentation part. If you requested all slides, including hidden slides, that is all there is to do. There is slightly more work to be done if you want to exclude hidden slides, as shown in the following code. - -### [C#](#tab/cs-3) -```csharp - if (includeHidden) - { - slidesCount = presentationPart.SlideParts.Count(); - } - else - { - // Code removed here… - } -``` - -### [Visual Basic](#tab/vb-3) -```vb - If includeHidden Then - slidesCount = presentationPart.SlideParts.Count() - Else - ' Code removed here… - End If -``` +If the presentation part reference is not null (and it will not be, for any valid presentation that loads correctly into PowerPoint), the code next calls the `Count` method on the value of the property of the presentation part. If you requested all slides, including hidden slides, that is all there is to do. There is slightly more work to be done if you want to exclude hidden slides, as shown in the following code. + +### [C#](#tab/cs) +[!code-csharp[](../../samples/presentation/retrieve_the_number_of_slides/cs/Program.cs#snippet4)] + +### [Visual Basic](#tab/vb) +[!code-vb[](../../samples/presentation/retrieve_the_number_of_slides/vb/Program.vb#snippet4)] *** + --------------------------------------------------------------------------------- ## Retrieving the Count of Visible Slides If you requested that the code should limit the return value to include only visible slides, the code must filter its collection of slides to -include only those slides that have a [Show](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.slide.show.aspx) property that contains a value, and -the value is **true**. If the **Show** property is null, that also indicates that -the slide is visible. This is the most likely scenario—PowerPoint does +include only those slides that have a property that contains a value, and +the value is `true`. If the `Show` property is null, that also indicates that +the slide is visible. This is the most likely scenario. PowerPoint does not set the value of this property, in general, unless the slide is to -be hidden. The only way the **Show** property -would exist and have a value of **true** would +be hidden. The only way the `Show` property +would exist and have a value of `true` would be if you had hidden and then unhidden the slide. The following code -uses the [Where](https://msdn2.microsoft.com/library/bb301979)** +uses the function with a lambda expression to do the work. -### [C#](#tab/cs-4) -```csharp - var slides = presentationPart.SlideParts.Where( - (s) => (s.Slide != null) && - ((s.Slide.Show == null) || (s.Slide.Show.HasValue && - s.Slide.Show.Value))); - slidesCount = slides.Count(); -``` - -### [Visual Basic](#tab/vb-4) -```vb - Dim slides = presentationPart.SlideParts. - Where(Function(s) (s.Slide IsNot Nothing) AndAlso - ((s.Slide.Show Is Nothing) OrElse - (s.Slide.Show.HasValue AndAlso - s.Slide.Show.Value))) - slidesCount = slides.Count() -``` +### [C#](#tab/cs) +[!code-csharp[](../../samples/presentation/retrieve_the_number_of_slides/cs/Program.cs#snippet5)] + +### [Visual Basic](#tab/vb) +[!code-vb[](../../samples/presentation/retrieve_the_number_of_slides/vb/Program.vb#snippet5)] *** @@ -179,14 +121,14 @@ function with a lambda expression to do the work. ## Sample Code -The following is the complete **RetrieveNumberOfSlides** code sample in C\# and +The following is the complete `RetrieveNumberOfSlides` code sample in C\# and Visual Basic. -### [C#](#tab/cs) -[!code-csharp[](../../samples/presentation/retrieve_the_number_of_slides/cs/Program.cs)] +### [C#](#tab/cs-2) +[!code-csharp[](../../samples/presentation/retrieve_the_number_of_slides/cs/Program.cs#snippet0)] -### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/presentation/retrieve_the_number_of_slides/vb/Program.vb)] +### [Visual Basic](#tab/vb-2) +[!code-vb[](../../samples/presentation/retrieve_the_number_of_slides/vb/Program.vb#snippet0)] --------------------------------------------------------------------------------- diff --git a/docs/presentation/overview.md b/docs/presentation/overview.md index f2dbeb7e..6e33d779 100644 --- a/docs/presentation/overview.md +++ b/docs/presentation/overview.md @@ -11,7 +11,7 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 08/12/2025 ms.localizationpriority: high --- # Presentations @@ -20,55 +20,62 @@ This section provides how-to topics for working with presentation documents usin ## In this section -- [Structure of a PresentationML document](structure-of-a-presentationml-document.md) - -- [Add a comment to a slide in a presentation](how-to-add-a-comment-to-a-slide-in-a-presentation.md) +- [Structure of a PresentationML document](structure-of-a-presentationml-document.md) -- [Apply a theme to a presentation](how-to-apply-a-theme-to-a-presentation.md) -- [Change the fill color of a shape in a presentation](how-to-change-the-fill-color-of-a-shape-in-a-presentation.md) +- [Add an audio file to a slide in a presentation](how-to-add-an-audio-to-a-slide-in-a-presentation.md) -- [Create a presentation document by providing a file name](how-to-create-a-presentation-document-by-providing-a-file-name.md) +- [Add a comment to a slide in a presentation](how-to-add-a-comment-to-a-slide-in-a-presentation.md) -- [Delete all the comments by an author from all the slides in a presentation](how-to-delete-all-the-comments-by-an-author-from-all-the-slides-in-a-presentatio.md) +- [Reply to a comment in a presentation](how-to-reply-to-a-comment-in-a-presentation.md) -- [Delete a slide from a presentation](how-to-delete-a-slide-from-a-presentation.md) +- [Apply a theme to a presentation](how-to-apply-a-theme-to-a-presentation.md) -- [Get all the external hyperlinks in a presentation](how-to-get-all-the-external-hyperlinks-in-a-presentation.md) +- [Change the fill color of a shape in a presentation](how-to-change-the-fill-color-of-a-shape-in-a-presentation.md) -- [Get all the text in a slide in a presentation](how-to-get-all-the-text-in-a-slide-in-a-presentation.md) +- [Create a presentation document by providing a file name](how-to-create-a-presentation-document-by-providing-a-file-name.md) -- [Get all the text in all slides in a presentation](how-to-get-all-the-text-in-all-slides-in-a-presentation.md) +- [Delete all the comments by an author from all the slides in a presentation](how-to-delete-all-the-comments-by-an-author-from-all-the-slides-in-a-presentation.md) -- [Get the titles of all the slides in a presentation](how-to-get-the-titles-of-all-the-slides-in-a-presentation.md) +- [Delete a slide from a presentation](how-to-delete-a-slide-from-a-presentation.md) -- [Insert a new slide into a presentation](how-to-insert-a-new-slide-into-a-presentation.md) +- [Get all the external hyperlinks in a presentation](how-to-get-all-the-external-hyperlinks-in-a-presentation.md) -- [Move a slide to a new position in a presentation](how-to-move-a-slide-to-a-new-position-in-a-presentation.md) +- [Get all the text in a slide in a presentation](how-to-get-all-the-text-in-a-slide-in-a-presentation.md) -- [Move a paragraph from one presentation to another](how-to-move-a-paragraph-from-one-presentation-to-another.md) +- [Get all the text in all slides in a presentation](how-to-get-all-the-text-in-all-slides-in-a-presentation.md) -- [Open a presentation document for read-only access](how-to-open-a-presentation-document-for-read-only-access.md) +- [Get the titles of all the slides in a presentation](how-to-get-the-titles-of-all-the-slides-in-a-presentation.md) -- [Retrieve the number of slides in a presentation document](how-to-retrieve-the-number-of-slides-in-a-presentation-document.md) +- [Insert a new slide into a presentation](how-to-insert-a-new-slide-into-a-presentation.md) -- [Working with animation](working-with-animation.md) +- [Move a slide to a new position in a presentation](how-to-move-a-slide-to-a-new-position-in-a-presentation.md) -- [Working with comments](working-with-comments.md) +- [Move a paragraph from one presentation to another](how-to-move-a-paragraph-from-one-presentation-to-another.md) -- [Working with handout master slides](working-with-handout-master-slides.md) +- [Open a presentation document for read-only access](how-to-open-a-presentation-document-for-read-only-access.md) -- [Working with notes slides](working-with-notes-slides.md) +- [Retrieve the number of slides in a presentation document](how-to-retrieve-the-number-of-slides-in-a-presentation-document.md) -- [Working with presentations](working-with-presentations.md) +- [Add a transition to a slides in a presentation](how-to-add-transitions-between-slides-in-a-presentation.md) -- [Working with presentation slides](working-with-presentation-slides.md) +- [Working with animation](working-with-animation.md) -- [Working with slide layouts](working-with-slide-layouts.md) +- [Working with comments](working-with-comments.md) -- [Working with slide masters](working-with-slide-masters.md) +- [Working with handout master slides](working-with-handout-master-slides.md) +- [Working with notes slides](working-with-notes-slides.md) -## Related sections +- [Working with presentations](working-with-presentations.md) -- [Getting started with the Open XML SDK for Office](../getting-started.md) +- [Working with presentation slides](working-with-presentation-slides.md) + +- [Working with slide layouts](working-with-slide-layouts.md) + +- [Working with slide masters](working-with-slide-masters.md) + + +## Related sections + +- [Getting started with the Open XML SDK for Office](../getting-started.md) diff --git a/docs/presentation/structure-of-a-presentationml-document.md b/docs/presentation/structure-of-a-presentationml-document.md index daadd7fc..afff4570 100644 --- a/docs/presentation/structure-of-a-presentationml-document.md +++ b/docs/presentation/structure-of-a-presentationml-document.md @@ -9,15 +9,15 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 09/16/2021 +ms.date: 11/26/2024 ms.localizationpriority: high --- # Structure of a PresentationML document -The document structure of a PresentationML document consists of the \ (Presentation) element that contains \ (Slide Master), \ (Slide Layout), \ (Slide), and \ (Theme) elements that reference the slides in the presentation. (The Theme element is the root element of the DrawingMLTheme part.) These elements are the minimum elements required for a valid presentation document. +The document structure of a PresentationML document consists of the `` (Presentation) element that contains `` (Slide Master), `` (Slide Layout), `` (Slide), and `` (Theme) elements that reference the slides in the presentation. (The Theme element is the root element of the DrawingMLTheme part.) These elements are the minimum elements required for a valid presentation document. -In addition, a presentation document might contain \ (Notes Slide), \ (Handout Master), \ (Shape), \ (Picture), \ (Table), and other slide-related elements. (Table elements are defined in the DrawingML schema.) +In addition, a presentation document might contain `` (Notes Slide), `` (Handout Master), `` (Shape), `` (Picture), `` (Table), and other slide-related elements. (Table elements are defined in the DrawingML schema.) Other features that a PresentationML document can contain include the following: animation, audio, video, and transitions between slides. @@ -25,33 +25,33 @@ A PresentationML document is not stored as one large body in a single part. Inst ## Important Presentation Parts -Using the Open XML SDK, you can create document structure and content that uses strongly-typed classes that correspond to PresentationML elements. You can find these classes in the **[DocumentFormat.OpenXml.Presentation](/dotnet/api/documentformat.openxml.presentation)** namespace. The following table lists the class names of the classes that correspond to some of the important presentation elements. +Using the Open XML SDK, you can create document structure and content that uses strongly-typed classes that correspond to PresentationML elements. You can find these classes in the namespace. The following table lists the class names of the classes that correspond to some of the important presentation elements. | **Package Part** | **Top Level PresentationML Element** | **Open XML SDK Class** | **Description**\* | |-------------------------|--------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Presentation | \ | [Presentation](/dotnet/api/documentformat.openxml.presentation.presentation) | The root element for the Presentation part. This element specifies within it fundamental presentation-wide properties. | -| Presentation Properties | \ | [PresentationProperties](/dotnet/api/documentformat.openxml.presentation.presentationproperties) | The root element for the Presentation Properties part. This element functions as a parent element within which additional presentation-wide document properties are contained. | -| Slide Master | \ | [SlideMaster](/dotnet/api/documentformat.openxml.presentation.slidemaster) | The root element for the Slide Master part. Within a slide master slide are contained all elements that describe the objects and their corresponding formatting for within a presentation slide. For more information, see [Working with slide masters](working-with-slide-masters.md). | -| Slide Layout | \ | [SlideLayout](/dotnet/api/documentformat.openxml.presentation.slidelayout) | The root element for the Slide Layout part. This element specifies the relationship information for each slide layout that is used within the slide master. For more information, see [Working with slide layouts](working-with-slide-layouts.md). | -| Theme | \ | [Theme](/dotnet/api/documentformat.openxml.drawing.theme) | The root element for the Theme part. This element holds all the different formatting options available to a document through a theme and defines the overall look and feel of the document when themed objects are used within the document. | -| Slide | \ | [Slide](/dotnet/api/documentformat.openxml.presentation.slide) | The root element for the Slide part. This element specifies a slide within a slide list. For more information, see [Working with presentation slides](working-with-presentation-slides.md). | -| Notes Master | \ | [NotesMaster](/dotnet/api/documentformat.openxml.presentation.notesmaster) | The root element for the Notes Master part. Within a notes master slide are contained all elements that describe the objects and their corresponding formatting for within a notes slide. | -| Notes Slide | \ | [NotesSlide](/dotnet/api/documentformat.openxml.presentation.notesslide) | The root element of the Notes Slide part. This element specifies the existence of a notes slide along with its corresponding data. Contained within a notes slide are all the common slide elements along with addition properties that are specific to the notes element. For more information, see [Working with notes slides](working-with-notes-slides.md). | -| Handout Master | \ | [HandoutMaster](/dotnet/api/documentformat.openxml.presentation.handoutmaster) | The root element of the Handout Master part. Within a handout master slide are contained all elements that describe the objects and their corresponding formatting for within a handout slide. For more information, see [Working with handout master slides](working-with-handout-master-slides.md). | -| Comments | \ | [CommentList](/dotnet/api/documentformat.openxml.presentation.commentlist) | The root element of the Comments part. This element specifies a list of comments for a particular slide. For more information, see [Working with comments](working-with-comments.md). | -| Comments Author | \ | [CommentAuthorList](/dotnet/api/documentformat.openxml.presentation.commentauthorlist) | The root element of the Comments Author part. This element specifies a list of authors with comments in the current document. For more information, see [Working with comments](working-with-comments.md). | - -*Descriptions adapted from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification, © ISO/IEC29500: 2008. +| Presentation | `` | | The root element for the Presentation part. This element specifies within it fundamental presentation-wide properties. | +| Presentation Properties | `` | | The root element for the Presentation Properties part. This element functions as a parent element within which additional presentation-wide document properties are contained. | +| Slide Master | `` | | The root element for the Slide Master part. Within a slide master slide are contained all elements that describe the objects and their corresponding formatting for within a presentation slide. For more information, see [Working with slide masters](working-with-slide-masters.md). | +| Slide Layout | `` | | The root element for the Slide Layout part. This element specifies the relationship information for each slide layout that is used within the slide master. For more information, see [Working with slide layouts](working-with-slide-layouts.md). | +| Theme | `` | | The root element for the Theme part. This element holds all the different formatting options available to a document through a theme and defines the overall look and feel of the document when themed objects are used within the document. | +| Slide | `` | | The root element for the Slide part. This element specifies a slide within a slide list. For more information, see [Working with presentation slides](working-with-presentation-slides.md). | +| Notes Master | `` | | The root element for the Notes Master part. Within a notes master slide are contained all elements that describe the objects and their corresponding formatting for within a notes slide. | +| Notes Slide | `` | | The root element of the Notes Slide part. This element specifies the existence of a notes slide along with its corresponding data. Contained within a notes slide are all the common slide elements along with addition properties that are specific to the notes element. For more information, see [Working with notes slides](working-with-notes-slides.md). | +| Handout Master | `` | | The root element of the Handout Master part. Within a handout master slide are contained all elements that describe the objects and their corresponding formatting for within a handout slide. For more information, see [Working with handout master slides](working-with-handout-master-slides.md). | +| Comments | `` | | The root element of the Comments part. This element specifies a list of comments for a particular slide. For more information, see [Working with comments](working-with-comments.md). | +| Comments Author | `` | | The root element of the Comments Author part. This element specifies a list of authors with comments in the current document. For more information, see [Working with comments](working-with-comments.md). | + +*Descriptions adapted from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification, © [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] ### Presentation Part -A PresentationML package's main part starts with a \ root element. That element contains a presentation, which, in turn, refers to a slide list, a slide master list, a notes master list, and a handout master list. The slide list refers to all of the slides in the presentation. The slide master list refers to the entire set of slide masters used in the presentation. The notes master contains information about the formatting of notes pages. The handout master describes how a handout looks. (A handout is a printed set of slides that can be handed out to an audience for future reference.) +A PresentationML package's main part starts with a `` root element. That element contains a presentation, which, in turn, refers to a slide list, a slide master list, a notes master list, and a handout master list. The slide list refers to all of the slides in the presentation. The slide master list refers to the entire set of slide masters used in the presentation. The notes master contains information about the formatting of notes pages. The handout master describes how a handout looks. (A handout is a printed set of slides that can be handed out to an audience for future reference.) ### Presentation Properties Part -The root element of the Presentation Properties part is the \ element. +The root element of the Presentation Properties part is the `` element. -The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification describes the Open XML PresentationML Presentation Properties part as follows: +The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification describes the Open XML PresentationML Presentation Properties part as follows: An instance of this part type contains all the presentation's properties. @@ -81,13 +81,13 @@ A Presentation Properties part shall be located within the package containing th A Presentation Properties part shall not have implicit or explicit relationships to any other part defined by ISO/IEC 29500. -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] ### Slide Master Part -The root element of the Slide Master part is the \ element. +The root element of the Slide Master part is the `` element. -The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification describes the Open XML PresentationML Slide Master part as follows: +The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification describes the Open XML PresentationML Slide Master part as follows: An instance of this part type contains the master definition of formatting, text, and objects that appear on each slide in the presentation that is derived from this slide master. @@ -141,19 +141,19 @@ following parts defined by ISO/IEC 29500: A Slide Master part shall not have implicit or explicit relationships to any other part defined by ISO/IEC 29500. -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] ### Slide Layout Part -The root element of the Slide Layout part is the \ element. +The root element of the Slide Layout part is the `` element. -The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification describes the Open XML PresentationML Slide Layout part as follows: +The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification describes the Open XML PresentationML Slide Layout part as follows: An instance of this part type contains the definition for a slide layout template for this presentation. This template defines the default appearance and positioning of drawing objects on this slide type when it is created. A package shall contain one or more Slide Layout parts, and each of those parts shall be the target of an explicit relationship in the Slide Master (§13.3.10) part, as well as an implicit relationship from each of the Slide (§13.3.8) parts associated with this slide layout. -Example: The following Slide Master part-relationship item contains relationships to several Slide Layout parts, which are stored in the ZIP items ../slideLayouts/slideLayoutN.xml: +Example: The following Slide Master part-relationship item contains relationships to several Slide Layout parts, which are stored in the ZIP items `../slideLayouts/slideLayoutN.xml`: ```xml @@ -207,21 +207,21 @@ A Slide Layout part is permitted to have explicit relationships to the following A Slide Layout part shall not have implicit or explicit relationships to any other part defined by ISO/IEC 29500. -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] ### Slide Part -The root element of the Slide part is the \ element. +The root element of the Slide part is the `` element. As well as text and graphics, each slide can contain comments and notes, can have a layout, and can be part of one or more custom presentations. A comment is an annotation intended for the person maintaining the presentation slide deck. A note is a reminder or piece of text intended for the presenter or the audience. -The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification describes the Open XML PresentationML Slide part as follows: +The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification describes the Open XML PresentationML Slide part as follows: A Slide part contains the contents of a single slide. A package shall contain one Slide part per slide, and each of those parts shall be the target of an explicit relationship from the Presentation (§13.3.6) part. -Example: Consider a PresentationML document having two slides. The corresponding Presentation part relationship item contains two relationships to Slide parts, which are stored in the ZIP items slides/slide1.xml and slides/slide2.xml: +Example: Consider a PresentationML document having two slides. The corresponding Presentation part relationship item contains two relationships to Slide parts, which are stored in the ZIP items `slides/slide1.xml and slides/slide2.xml`: ```xml @@ -232,9 +232,9 @@ Example: Consider a PresentationML document having two slides. The corresponding ``` -The root element for a part of this content type shall be sld. +The root element for a part of this content type shall be ``. -Example: slides/slide1.xml contains: +Example: `slides/slide1.xml` contains: ```xml @@ -285,19 +285,19 @@ A Slide part is permitted to have explicit relationships to the following parts A Slide part shall not have implicit or explicit relationships to any other part defined by ISO/IEC 29500. -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] ### Theme Part -The root element of the Theme part is the \ element. +The root element of the Theme part is the `` element. -The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification describes the Open XML DrawingML Theme part as follows: +The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification describes the Open XML DrawingML Theme part as follows: -An instance of this part type contains information about a document's theme, which is a combination of color scheme, font scheme, and format scheme (the latter also being referred to as effects). For a WordprocessingML document, the choice of theme affects the color and style of headings, among other things. For a SpreadsheetML document, the choice of theme affects the color and style of cell contents and charts, among other things. For a PresentationML document, the choice of theme affects the formatting of slides, handouts, and notes via the associated master, among other things. +An instance of this part type contains information about a document's theme, which is a combination of color scheme, font scheme, and format scheme (the latter also being referred to as effects). For a WordprocessingML document, the choice of theme affects the color and style of headings, among other things. For a SpreadsheetML document, the choice of theme affects the color and style of cell contents and charts, among other things. For a PresentationML document, the choice of theme affects the formatting of slides, handouts, and notes via the associated master, in addition to other things. A WordprocessingML or SpreadsheetML package shall contain zero or one Theme part, which shall be the target of an implicit relationship in a Main Document (§11.3.10) or Workbook (§12.3.23) part. A PresentationML package shall contain zero or one Theme part per Handout Master (§13.3.3), Notes Master (§13.3.4), Slide Master (§13.3.10) or Presentation (§13.3.6) part via an implicit relationship. -Example: The following WordprocessingML Main Document part-relationship item contains a relationship to the Theme part, which is stored in the ZIP item theme/theme1.xml: +Example: The following WordprocessingML Main Document part-relationship item contains a relationship to the Theme part, which is stored in the ZIP item `theme/theme1.xml`: ```xml @@ -335,13 +335,13 @@ A Theme part is permitted to contain explicit relationships to the following par A Theme part shall not have any implicit or explicit relationships to other parts defined by ISO/IEC 29500. -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] ### Notes Master Part -The root element of the Notes Master part is the \ element. +The root element of the Notes Master part is the `` element. -The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification describes the Open XML PresentationML Notes Master part as follows: +The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification describes the Open XML PresentationML Notes Master part as follows: An instance of this part type contains information about the content and formatting of all notes pages. @@ -393,19 +393,19 @@ A Notes Master part is permitted to have explicit relationships to the following The Notes Master part shall not have implicit or explicit relationships to any other part defined by ISO/IEC 29500. -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] ### Notes Slide Part -The root element of the Notes Slide part is the \ element. +The root element of the Notes Slide part is the `` element. -The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification describes the Open XML PresentationML Notes Slide part as follows: +The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification describes the Open XML PresentationML Notes Slide part as follows: An instance of this part type contains the notes for a single slide. A package shall contain one Notes Slide part for each slide that contains notes. If they exist, those parts shall each be the target of an implicit relationship from the Slide (§13.3.8) part. -Example: The following Slide part-relationship item contains a relationship to a Notes Slide part, which is stored in the ZIP item ../notesSlides/notesSlide1.xml: +Example: The following Slide part-relationship item contains a relationship to a Notes Slide part, which is stored in the ZIP item `../notesSlides/notesSlide1.xml`: ```xml @@ -454,20 +454,20 @@ A Notes Slide part is permitted to have explicit relationships to the following The Notes Slide part shall not have implicit or explicit relationships to any other part defined by ISO/IEC 29500. -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] ### Handout Master Part -The root element of the Handout Master part is the \ element. +The root element of the Handout Master part is the `` element. -The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification describes the Open XML PresentationML Handout Master part as follows: +The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification describes the Open XML PresentationML Handout Master part as follows: An instance of this part type contains the look, position, and size of the slides, notes, header and footer text, date, or page number on the presentation's handout. A package shall contain at most one Handout Master part, and it shall be the target of an explicit relationship from the Presentation (§13.3.6) part. Example: The following Presentation part-relationship item contains a relationship to the Handout Master part, which is stored in the ZIP item -handoutMasters/handoutMaster1.xml: +`handoutMasters/handoutMaster1.xml`: ```xml @@ -513,20 +513,20 @@ A Handout Master part is permitted to have explicit relationships to the followi A Handout Master part shall not have implicit or explicit relationships to any other part defined by ISO/IEC 29500. -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] ### Comments Part -The root element of the Comments part is the \ element. +The root element of the Comments part is the `` element. -The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification describes the Open XML PresentationML Comments part as +The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification describes the Open XML PresentationML Comments part as follows: An instance of this part type contains the comments for a single slide. Each comment is tied to its author via an author-ID. Each comment's index number and author-ID combination are unique. A package shall contain one Comments part for each slide containing one or more comments, and each of those parts shall be the target of an implicit relationship from its corresponding Slide (§13.3.8) part. -Example: The following Slide part-relationship item contains a relationship to a Comments part, which is stored in the ZIP item ../comments/comment2.xml: +Example: The following Slide part-relationship item contains a relationship to a Comments part, which is stored in the ZIP item `../comments/comment2.xml`: ```xml @@ -536,7 +536,7 @@ Example: The following Slide part-relationship item contains a relationship to a ``` -The root element for a part of this content type shall be cmLst. +The root element for a part of this content type shall be ``. Example: The Comments part contains three comments, two created by one author, and one created by another, all at the dates and times shown. The index numbers are assigned on a per-author basis, starting at 1 for an author's first comment: @@ -561,20 +561,20 @@ A Comments part shall be located within the package containing the relationships A Comments part shall not have implicit or explicit relationships to any other part defined by ISO/IEC 29500. -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] ### Comments Author Part -The root element of the Comments Author part is the \ +The root element of the Comments Author part is the `` element. -The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification describes the Open XML PresentationML Comments Author part as follows: +The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification describes the Open XML PresentationML Comments Author part as follows: An instance of this part type contains information about each author who has added a comment to the document. That information includes the author's name, initials, a unique author-ID, a last-comment-index-used count, and a display color. (The color can be used when displaying comments to distinguish comments from different authors.) A package shall contain at most one Comment Authors part. If it exists, that part shall be the target of an implicit relationship from the Presentation (§13.3.6) part. -Example: The following Presentation part relationship item contains a relationship to the Comment Authors part, which is stored in the ZIP item commentAuthors.xml: +Example: The following Presentation part relationship item contains a relationship to the Comment Authors part, which is stored in the ZIP item `commentAuthors.xml`: ```xml @@ -583,7 +583,7 @@ Example: The following Presentation part relationship item contains a relationsh ``` -The root element for a part of this content type shall be cmAuthorLst. +The root element for a part of this content type shall be ``. Example: Two people have authored comments in this document: Mary Smith and Peter Jones. Her initials are "mas", her author-ID is 0, and her comments' display color index is 0. Since Mary's last-comment-index-used value is 3, the next comment-index to be used for her is 4. His initials are "pjj", his author-ID is 1, and his comments' display color index is 1. Since Peter's last-comment-index-used value is 1, the next comment-index to be used for him is 2: @@ -600,7 +600,7 @@ A Comment Authors part shall be located within the package containing the relati A Comment Authors part shall not have implicit or explicit relationships to any other part defined by ISO/IEC 29500. -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] ## The Structure of a Minimum Presentation File @@ -612,30 +612,30 @@ The packaging structure of a presentation document contains several references b ## Generated PresentationML XML Code -After you run the Open XML SDK code to generate a presentation, you can explore the contents of the .zip package to view the PresentationML XML code. To view the .zip package, rename the extension on the minimum presentation from **.pptx** to **.zip**. Inside the .zip package, there are several parts that make up the minimum presentation. +After you run the Open XML SDK code to generate a presentation, you can explore the contents of the .zip package to view the PresentationML XML code. To view the .zip package, rename the extension on the minimum presentation from `.pptx` to `.zip`. Inside the .zip package, there are several parts that make up the minimum presentation. -Figure 1 shows the structure under the **ppt** folder of the .zip package for a minimum presentation that contains a single slide. +Figure 1 shows the structure under the `ppt` folder of the zip package for a minimum presentation that contains a single slide. Figure 1. Minimum presentation folder structure ![Minimum presentation folder structure](../media/odc_oxml_ppt_documentstructure_fig01.jpg) -The presentation.xml file contains \ (Slide) elements that reference the slides in the presentation. Each slide is associated to the presentation by means of a slide ID and a relationship ID. The **slideID** is the identifier (ID) used within the package to identify a slide and must be unique within the presentation. The **id** attribute is the relationship ID that identifies the slide part definition associated with a slide. For more information about the slide part, see [Working with presentation slides](working-with-presentation-slides.md). +The presentation.xml file contains `` (Slide) elements that reference the slides in the presentation. Each slide is associated to the presentation by means of a slide ID and a relationship ID. The `slideID` is the identifier (ID) used within the package to identify a slide and must be unique within the presentation. The `id` attribute is the relationship ID that identifies the slide part definition associated with a slide. For more information about the slide part, see [Working with presentation slides](working-with-presentation-slides.md). The following XML code is the PresentationML that represents the presentation part of a presentation document that contains a single slide. This code is generated when you run the Open XML SDK code to create a minimum presentation. ```xml - + + xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" /> + xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" /> - + @@ -667,7 +667,7 @@ The following XML code is the PresentationML that represents the slide part of t ```xml - + @@ -677,7 +677,7 @@ The following XML code is the PresentationML that represents the slide part of t - + @@ -685,7 +685,7 @@ The following XML code is the PresentationML that represents the slide part of t name="Title 1" /> + xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" /> @@ -693,9 +693,9 @@ The following XML code is the PresentationML that represents the slide part of t - - - + + + @@ -703,14 +703,14 @@ The following XML code is the PresentationML that represents the slide part of t - + ``` ## Typical Presentation Scenario -A typical presentation does not have a minimum configuration. A typical presentation might contain several slides, each of which references slide layouts and slide masters, and which might contain comments. In addition, a presentation might contain handouts and notes slides, each of which is represented by separate parts. These additional parts are contained within the .zip package of the presentation document. +A typical presentation does not have a minimum configuration. A typical presentation might contain several slides, each of which references slide layouts and slide masters, and which might contain comments. In addition, a presentation might contain handouts and notes slides, each of which is represented by separate parts. These additional parts are contained within the zip package of the presentation document. Figure 2 shows most of the elements that you would find in a typical presentation. diff --git a/docs/presentation/working-with-animation.md b/docs/presentation/working-with-animation.md index 4a526887..18ce5c48 100644 --- a/docs/presentation/working-with-animation.md +++ b/docs/presentation/working-with-animation.md @@ -11,19 +11,19 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 11/26/2024 ms.localizationpriority: medium --- # Working with animation -This topic discusses the Open XML SDK for Office **Animate** class and how it relates to the Open XML File Format PresentationML schema. For more information about the overall structure of the parts and elements that make up a PresentationML document, see [Structure of a PresentationML Document](structure-of-a-presentationml-document.md). +This topic discusses the Open XML SDK for Office `Animate` class and how it relates to the Open XML File Format PresentationML schema. For more information about the overall structure of the parts and elements that make up a PresentationML document, see [Structure of a PresentationML Document](structure-of-a-presentationml-document.md). ## Animation in PresentationML -The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification describes the Animation section of the Open XML PresentationML framework as follows: +The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification describes the Animation section of the Open XML PresentationML framework as follows: -The Animation section of the PresentationML framework stores the movement and related information of objects. This schema is loosely based on the syntax and concepts from the Synchronized Multimedia Integration Language (SMIL), a W3C Recommendation for describing multimedia presentations using XML. The schema describes all the animations effects that reside on a slide and also the animation that occurs when going from slide to slide (slide transition). Animations on a slide are inherently time-based and consist of an animation effects on an object or text. Slide transitions however do not follow this concept and always appear before any animation on a slide. All elements described in this schema are contained within the slide XML file. More specifically they are in the \ and the \ element as shown below: +The Animation section of the PresentationML framework stores the movement and related information of objects. This schema is loosely based on the syntax and concepts from the Synchronized Multimedia Integration Language (SMIL), a W3C Recommendation for describing multimedia presentations using XML. The schema describes all the animations effects that reside on a slide and also the animation that occurs when going from slide to slide (slide transition). Animations on a slide are inherently time-based and consist of an animation effects on an object or text. Slide transitions however do not follow this concept and always appear before any animation on a slide. All elements described in this schema are contained within the slide XML file. More specifically they are in the `` and the `` element as shown below: ```xml @@ -34,9 +34,9 @@ The Animation section of the PresentationML framework stores the movement and re ``` -Animation consists of several behaviors, the most basic of which is the Animate behavior, represented by the \ element. The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification describes the Open XML PresentationML \ element used to represent basic animation behavior in a PresentationML document as follows: +Animation consists of several behaviors, the most basic of which is the Animate behavior, represented by the `` element. The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification describes the Open XML PresentationML `` element used to represent basic animation behavior in a PresentationML document as follows: -This element is a generic animation element that requires little or no semantic understanding of the attribute being animated. It can animate text within a shape or even the shape itself.[Example: Consider trying to emphasize text within a shape by changing the size of its font by 150%. The \ element should be used as follows: +This element is a generic animation element that requires little or no semantic understanding of the attribute being animated. It can animate text within a shape or even the shape itself.[Example: Consider trying to emphasize text within a shape by changing the size of its font by 150%. The `` element should be used as follows: ```xml @@ -56,14 +56,14 @@ This element is a generic animation element that requires little or no semantic ``` -The following table lists the child elements of the \ element used when working with animation and the Open XML SDK classes that correspond to them. +The following table lists the child elements of the `` element used when working with animation and the Open XML SDK classes that correspond to them. | **PresentationML Element** | **Open XML SDK Class** | |:---------------------------|:----------------------------| -| \ | CommonBehavior | -| \ | TimeAnimateValueList | +| `` | | +| `` | | -The following table from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification describes the attributes of the \ element. +The following table from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification describes the attributes of the `` element. | **Attributes** | **Description** | |:---------------|:-----------------------------------------------------------------| @@ -75,18 +75,18 @@ The following table from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalog ## Open XML SDK Animate Class -The OXML SDK **Animate** class represents the \ element defined in the Open XML File Format schema for PresentationML documents. Use the **Animate** -class to manipulate individual \ elements in a PresentationML document. +The OXML SDK `Animate` class represents the `` element defined in the Open XML File Format schema for PresentationML documents. Use the `Animate` +class to manipulate individual `` elements in a PresentationML document. -Classes that represent child elements of the \ element and that are therefore commonly associated with the **Animate** class are shown in the following list. +Classes that represent child elements of the `` element and that are therefore commonly associated with the `Animate` class are shown in the following list. ### CommonBehavior Class -The **CommonBehavior** class corresponds to the \ element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification introduces the \element: +The `CommonBehavior` class corresponds to the `` element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification introduces the ``element: This element describes the common behaviors of animations. -Consider trying to emphasize text within a shape by changing the size of its font. The \ element should be used as follows: +Consider trying to emphasize text within a shape by changing the size of its font. The `` element should be used as follows: ```xml @@ -108,11 +108,11 @@ Consider trying to emphasize text within a shape by changing the size of its fon ### TimeAnimateValueList Class -The **TimeAnimateValueList** class corresponds to the \ element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification introduces the \ element: +The `TimeAnimateValueList` class corresponds to the `` element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification introduces the `` element: This element specifies a list of time animated value elements. -Example: Consider a shape with a "fly-in" animation. The \ element should be used as follows: +Example: Consider a shape with a "fly-in" animation. The `` element should be used as follows: ```xml @@ -134,7 +134,7 @@ Example: Consider a shape with a "fly-in" animation. The \ element should ## Working with the Animate Class -The **Animate** class, which represents the \ element, is therefore also associated with other classes that represent the child elements of the \ element, including the **CommonBehavior** class, which describes common animation behaviors, and the **TimeAnimateValueList** class, which specifies a list of time-animated value elements, as shown in the previous XML code. Other classes associated with the **Animate** class are the **Timing** class, which specifies timing information for all the animations on the slide, and the **TargetElement** class, which specifies the target child elements to which the animation effects are applied. +The `Animate` class, which represents the `` element, is therefore also associated with other classes that represent the child elements of the `` element, including the `CommonBehavior` class, which describes common animation behaviors, and the `TimeAnimateValueList` class, which specifies a list of time-animated value elements, as shown in the previous XML code. Other classes associated with the `Animate` class are the class, which specifies timing information for all the animations on the slide, and the class, which specifies the target child elements to which the animation effects are applied. ## See also diff --git a/docs/presentation/working-with-comments.md b/docs/presentation/working-with-comments.md index 982dee9e..9b8b0409 100644 --- a/docs/presentation/working-with-comments.md +++ b/docs/presentation/working-with-comments.md @@ -11,18 +11,17 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 11/26/2024 ms.localizationpriority: medium --- # Working with comments -This topic discusses the Open XML SDK for Office [Comment](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.comment.aspx) class and how it relates to the -Open XML File Format PresentationML schema. For more information about the overall structure of the parts and elements that make up a PresentationML document, see [Structure of a PresentationML -Document](structure-of-a-presentationml-document.md). +This topic discusses the Open XML SDK for Office class and how it relates to the +Open XML File Format PresentationML schema. For more information about the overall structure of the parts and elements that make up a PresentationML document, see [Structure of a PresentationML Document](structure-of-a-presentationml-document.md). ## Comments in PresentationML -The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification describes the Comments section of the Open XML PresentationML framework as follows: +The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification describes the Comments section of the Open XML PresentationML framework as follows: A comment is a text note attached to a slide, with the primary purpose of allowing readers of a presentation to provide feedback to the @@ -33,7 +32,7 @@ presentation, but do not appear when a slide show is given. The displaying application decides when to display comments and determines their visual appearance. -The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification describes the Open XML PresentationML \ element used to represent comments in a PresentationML document as follows: +The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification describes the Open XML PresentationML `` element used to represent comments in a PresentationML document as follows: This element specifies a single comment attached to a slide. It contains the text of the comment, its position on the slide, and attributes @@ -48,46 +47,46 @@ Example: ``` -The following table lists the child elements of the \ element used when working with comments and the Open XML SDK classes that correspond to them. +The following table lists the child elements of the `` element used when working with comments and the Open XML SDK classes that correspond to them. | **PresentationML Element** | **Open XML SDK Class** | |----------------------------|------------------------------------------------------------------------------------------------------------------------------------------| -| \ | [ExtensionListWithModification](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.extensionlistwithmodification.aspx) | -| \ | [Position](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.position.aspx) | -| \ | [Text](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.text.aspx) | +| `` | | +| `` | | +| `` | | -The following table from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification describes the attributes of the \ element. +The following table from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification describes the attributes of the `` element. | **Attributes** | **Description** | |----------------|--------------------| -| authorId | This attribute specifies the author of the comment.It refers to the ID of an author in the comment author list for the document.
The possible values for this attribute are defined by the W3C XML Schema **unsignedInt** datatype. | -| dt | This attribute specifies the date and time this comment was last modified.
The possible values for this attribute are defined by the W3C XML Schema **datetime** datatype. | +| authorId | This attribute specifies the author of the comment.It refers to the ID of an author in the comment author list for the document.
The possible values for this attribute are defined by the W3C XML Schema `unsignedInt` datatype. | +| dt | This attribute specifies the date and time this comment was last modified.
The possible values for this attribute are defined by the W3C XML Schema `datetime` datatype. | | idx | This attribute specifies an identifier for this comment that is unique within a list of all comments by this author in this document. An author's first comment in a document has index 1.
Note: Because the index is unique only for the comment author, a document can contain multiple comments with the same index created by different authors.
The possible values for this attribute are defined by the ST_Index simple type (§19.7.3). | ## Open XML SDK Comment Class -The OXML SDK **Comment** class represents the \ element defined in the Open XML File Format schema for PresentationML documents. Use the **Comment** -class to manipulate individual \ elements in a PresentationML document. +The OXML SDK `Comment` class represents the `` element defined in the Open XML File Format schema for PresentationML documents. Use the `Comment` +class to manipulate individual `` elements in a PresentationML document. -Classes that represent child elements of the \ element and that are -therefore commonly associated with the **Comment** class are shown in the following list. +Classes that represent child elements of the `` element and that are +therefore commonly associated with the `Comment` class are shown in the following list. ### ExtensionListWithModification Class -The **ExtensionListWithModification** class corresponds to the \element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification introduces the \ element: +The `ExtensionListWithModification` class corresponds to the ``element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification introduces the `` element: -This element specifies the extension list with modification ability within which all future extensions of element type \ are defined. The extension list along with corresponding future extensions is used to extend the storage capabilities of the PresentationML framework. This allows for various new kinds of data to be stored natively within the framework. +This element specifies the extension list with modification ability within which all future extensions of element type `` are defined. The extension list along with corresponding future extensions is used to extend the storage capabilities of the PresentationML framework. This allows for various new kinds of data to be stored natively within the framework. > [!NOTE] -> Using this extLst element allows the generating application to store whether this extension property has been modified. end note +> Using this `extLst` element allows the generating application to store whether this extension property has been modified. end note ### Position Class -The **Position** class corresponds to the -\element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification introduces the \ element: +The `Position` class corresponds to the +``element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification introduces the `` element: This element specifies the positioning information for the placement of a comment on a slide surface. In LTR versions of the generating @@ -109,15 +108,15 @@ application chooses to display comments. end note] ### Text class -The **Text** class corresponds to the -\element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification introduces the \ element: +The `Text` class corresponds to the +`` element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification introduces the `` element: This element specifies the content of a comment. This is the text with which the author has annotated the slide. The possible values for this element are defined by the W3C XML Schema -**string** datatype. +`string` datatype. ## Working with the Comment Class @@ -131,111 +130,29 @@ displaying application decides when to display comments and determines their visual appearance. As shown in the Open XML SDK code sample that follows, every instance of -the **Comment** class is associated with an -instance of the [SlideCommentsPart](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.slidecommentspart.aspx) class, which represents a +the `Comment` class is associated with an +instance of the class, which represents a slide comments part, one of the parts of a PresentationML presentation file package, and a part that is required for each slide in a -presentation file that contains comments. Each **Comment** class instance is also associated with an -instance of the [CommentAuthor](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.commentauthor.aspx) class, which is in turn +presentation file that contains comments. Each `Comment` class instance is also associated with an +instance of the class, which is in turn associated with a similarly named presentation part, represented by the -[CommentAuthorsPart](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.commentauthorspart.aspx) class. Comment authors + class. Comment authors for a presentation are specified in a comment author list, represented -by the [CommentAuthorList](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.commentauthorlist.aspx) class, while comments for +by the class, while comments for each slide are listed in a comments list for that slide, represented by -the [CommentList](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.commentlist.aspx) class. +the class. -The **Comment** class, which represents the \ element, is therefore also associated with other classes that represent the child elements of the \ element. Among these classes, as shown in the following code sample, are the **Position** class, which specifies the position of the comment relative to the slide, and the **Text** class, which specifies the text content of the comment. +The `Comment` class, which represents the `` element, is therefore also associated with other classes that represent the child elements of the `` element. Among these classes, as shown in the following code sample, are the `Position` class, which specifies the position of the comment relative to the slide, and the `Text` class, which specifies the text content of the comment. ## Open XML SDK Code Example -The following code segment from the article [How to: Add a comment to a slide in a presentation](how-to-add-a-comment-to-a-slide-in-a-presentation.md) adds a new comments part to an existing slide in a presentation (if the slide does not already contain comments) and creates an instance of an Open XML SDK **Comment** class in the slide comments part. It also adds a comment list to the comments part by creating an instance of the **CommentList** class, if one does not already exist; assigns an ID to the comment; and then adds a comment to the comment list by creating an instance of the **Comment** class, assigning the required attribute values. In addition, it creates instances of the **Position** and **Text** classes associated with the new **Comment** class instance. For the complete code sample, see the aforementioned article. +The following code segment from the article [How to: Add a comment to a slide in a presentation](how-to-add-a-comment-to-a-slide-in-a-presentation.md) adds a new comments part to an existing slide in a presentation (if the slide does not already contain comments) and creates an instance of an Open XML SDK `Comment` class in the slide comments part. It also adds a comment list to the comments part by creating an instance of the `CommentList` class, if one does not already exist; assigns an ID to the comment; and then adds a comment to the comment list by creating an instance of the `Comment` class, assigning the required attribute values. In addition, it creates instances of the `Position` and `Text` classes associated with the new `Comment` class instance. For the complete code sample, see the aforementioned article. ### [C#](#tab/cs) -```csharp -// Declare a comments part. -SlideCommentsPart commentsPart; - -// Verify that there is a comments part in the first slide part. -if (slidePart1.GetPartsOfType().Count() == 0) -{ - // If not, add a new comments part. - commentsPart = slidePart1.AddNewPart(); -} -else -{ - // Else, use the first comments part in the slide part. - commentsPart = slidePart1.GetPartsOfType().First(); -} - -// If the comment list does not exist. -if (commentsPart.CommentList is null) -{ - // Add a new comments list. - commentsPart.CommentList = new CommentList(); -} - -// Get the new comment ID. -uint commentIdx = author.LastIndex is null ? 1 : author.LastIndex + 1; -author.LastIndex = commentIdx; - -// Add a new comment. -Comment comment = commentsPart.CommentList.AppendChild( - new Comment() - { - AuthorId = authorId, - Index = commentIdx, - DateTime = DateTime.Now - }); - -// Add the position child node to the comment element. -comment.Append( - new Position() { X = 100, Y = 200 }, - new Text() { Text = text }); -``` - +[!code-csharp[](../../samples/presentation/add_comment/cs/Program.cs#extsnippet1)] ### [Visual Basic](#tab/vb) -```vb -' Declare a comments part. -Dim commentsPart As SlideCommentsPart - -' Verify that there is a comments part in the first slide part. -If slidePart1.GetPartsOfType(Of SlideCommentsPart)().Count() = 0 Then - - ' If not, add a new comments part. - commentsPart = slidePart1.AddNewPart(Of SlideCommentsPart)() -Else - - ' Else, use the first comments part in the slide part. - commentsPart = -slidePart1.GetPartsOfType(Of SlideCommentsPart)().First() -End If - -' If the comment list does not exist. -If (commentsPart.CommentList Is Nothing) Then - - ' Add a new comments list. - commentsPart.CommentList = New CommentList() -End If - -' Get the new comment ID. -Dim commentIdx As UInteger -If author.LastIndex Is Nothing Then - commentIdx = 1 -Else - commentIdx = CType(author.LastIndex, UInteger) + 1 -End If - -author.LastIndex = commentIdx - -' Add a new comment. -Dim comment As Comment = -(commentsPart.CommentList.AppendChild(Of Comment)(New Comment() _ -With {.AuthorId = authorId, .Index = commentIdx, .DateTime = DateTime.Now})) - -' Add the position child node to the comment element. -comment.Append(New Position() With - {.X = 100, .Y = 200}, New Text() With {.Text = text}) -``` +[!code-vb[](../../samples/presentation/add_comment/vb/Program.vb#extsnippet1)] ## Generated PresentationML @@ -245,7 +162,7 @@ or comment authors before the code was run. ```xml - + - + @@ -276,4 +193,4 @@ article. [About the Open XML SDK for Office](../about-the-open-xml-sdk.md) [How to: Create a Presentation by Providing a File Name](how-to-create-a-presentation-document-by-providing-a-file-name.md) [How to: Add a comment to a slide in a presentation](how-to-add-a-comment-to-a-slide-in-a-presentation.md) -[How to: Delete all the comments by an author from all the slides in a presentation](how-to-delete-all-the-comments-by-an-author-from-all-the-slides-in-a-presentatio.md) +[How to: Delete all the comments by an author from all the slides in a presentation](how-to-delete-all-the-comments-by-an-author-from-all-the-slides-in-a-presentation.md) diff --git a/docs/presentation/working-with-handout-master-slides.md b/docs/presentation/working-with-handout-master-slides.md index fdca2df5..e06ad630 100644 --- a/docs/presentation/working-with-handout-master-slides.md +++ b/docs/presentation/working-with-handout-master-slides.md @@ -11,15 +11,15 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 01/21/2025 ms.localizationpriority: medium --- # Working with handout master slides -This topic discusses the Open XML SDK for Office [HandoutMaster](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.handoutmaster.aspx) class and how it relates to the Open XML File Format PresentationML schema. For more information about the overall structure of the parts and elements that make up a PresentationML document, see [Structure of a PresentationML document](structure-of-a-presentationml-document.md). +This topic discusses the Open XML SDK for Office class and how it relates to the Open XML File Format PresentationML schema. For more information about the overall structure of the parts and elements that make up a PresentationML document, see [Structure of a PresentationML document](structure-of-a-presentationml-document.md). ## Handout Master Slides in PresentationML -The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification describes the Open XML PresentationML \ +The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification describes the Open XML PresentationML `` element used to represent a handout master slide in a PresentationML document as follows: This element specifies an instance of a handout master slide. Within a @@ -30,29 +30,29 @@ slide elements such as shapes and their attached text bodies. There are other properties within a handout master slide but cSld encompasses the majority of the intended purpose for a handoutMaster slide. -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] -The following table lists the child elements of the \ +The following table lists the child elements of the `` element used when working with handout master slides and the Open XML SDK classes that correspond to them. -| **PresentationML Element** | **Open XML SDK Class** | -|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------| -| \ | [ColorMap](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.colormap.aspx) | -| \ | [CommonSlideData](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.commonslidedata.aspx) | -| \ | [ExtensionListWithModification](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.extensionlistwithmodification.aspx) | -| \ | [HeaderFooter](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.headerfooter.aspx) | +| **PresentationML Element** | **Open XML SDK Class** | +|----------------------------|--------------------------------------------------------------------------------------| +| `` | | +| `` | | +| `` | | +| `` | | ## Open XML SDK HandoutMaster Class -The Open XML SDK **HandoutMaster** class represents the \ element defined in the Open XML File Format schema for PresentationML documents. Use the **HandoutMaster** class to manipulate individual \ elements in a PresentationML document. +The Open XML SDK `HandoutMaster` class represents the `` element defined in the Open XML File Format schema for PresentationML documents. Use the `HandoutMaster` class to manipulate individual `` elements in a PresentationML document. -Classes commonly associated with the **HandoutMaster** class are shown in the following sections. +Classes commonly associated with the `HandoutMaster` class are shown in the following sections. ### ColorMap Class -The **ColorMap** class corresponds to the \ element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification introduces the \ element: +The `ColorMap` class corresponds to the `` element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification introduces the `` element: This element specifies the mapping layer that transforms one color scheme definition to another. Each attribute represents a color name @@ -71,30 +71,30 @@ accent6="accent6" hlink="hlink" folHlink="folHlink"/> ### CommonSlideData Class -The **CommonSlideData** class corresponds to -the \ element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification introduces the \ element: +The `CommonSlideData` class corresponds to +the `` element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification introduces the `` element: This element specifies a container for the type of slide information that is relevant to all of the slide types. All slides share a common set of properties that is independent of the slide type; the description of these properties for any particular slide is stored within the -slide's \ container. Slide data specific to the slide type +slide's `` container. Slide data specific to the slide type indicated by the parent element is stored elsewhere. -The actual data in \ describe only the particular parent slide; +The actual data in `` describe only the particular parent slide; it is only the type of information stored that is common across all slides. ### ExtensionListWithModification Class -The **ExtensionListWithModification** class -corresponds to the \element. The following information from the -[ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification introduces the \ element: +The `ExtensionListWithModification` class +corresponds to the `` element. The following information from the +[!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification introduces the `` element: This element specifies the extension list with modification ability -within which all future extensions of element type \ are defined. +within which all future extensions of element type `` are defined. The extension list along with corresponding future extensions is used to extend the storage capabilities of the PresentationML framework. This allows for various new kinds of data to be stored natively within the @@ -106,9 +106,9 @@ store whether this extension property has been modified. ### HeaderFooter Class -The **HeaderFooter** class corresponds to the -\ element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification introduces the \ element: +The `HeaderFooter` class corresponds to the +`` element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification introduces the `` element: This element specifies the header and footer information for a slide. Headers and footers consist of placeholders for text that should be @@ -119,37 +119,37 @@ slide numbering, and custom header and footer text. ## Working with the HandoutMaster Class As shown in the Open XML SDK code sample that follows, every instance of -the **HandoutMaster** class is associated with -an instance of the [HandoutMasterPart](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.handoutmasterpart.aspx) class, which represents a +the `HandoutMaster` class is associated with +an instance of the class, which represents a handout master part, one of the parts of a PresentationML presentation file package, and a part that is required for a presentation file that contains handouts. -The **HandoutMaster** class, which represents -the \ element, is therefore also associated with a +The `HandoutMaster` class, which represents +the `` element, is therefore also associated with a series of other classes that represent the child elements of the -\ element. Among these classes, as shown in the -following code sample, are the **CommonSlideData** class, the **ColorMap** class, the [ShapeTree](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.shapetree.aspx) class, and the [Shape](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.shape.aspx) class. +`` element. Among these classes, as shown in the +following code sample, are the `CommonSlideData` class, the `ColorMap` class, the class, and the class. ## Open XML SDK Code Example The following method adds a new handout master part to an existing -presentation and creates an instance of an Open XML SDK**HandoutMaster** class in the new handout master -part. The **HandoutMaster** class constructor -creates instances of the **CommonSlideData** -class and the **ColorMap** class. The **CommonSlideData** class constructor creates an -instance of the [ShapeTree](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.shapetree.aspx) class, whose constructor, in -turn, creates additional class instances: an instance of the [NonVisualGroupShapeProperties](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.nonvisualgroupshapeproperties.aspx) class, an -instance of the [GroupShapeProperties](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.groupshapeproperties.aspx) class, and an instance -of the [Shape](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.shape.aspx) class. - -The namespace represented by the letter *P* in the code is the [DocumentFormat.OpenXml.Presentation](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.aspx) +presentation and creates an instance of an Open XML SDK `HandoutMaster` class in the new handout master +part. The `HandoutMaster` class constructor +creates instances of the `CommonSlideData` +class and the `ColorMap` class. The `CommonSlideData` class constructor creates an +instance of the class, whose constructor, in +turn, creates additional class instances: an instance of the class, an +instance of the class, and an instance +of the class. + +The namespace represented by the letter `P` in the code is the namespace. ### [C#](#tab/cs) -[!code-csharp[](../../samples/presentation/working_with_handout_master_slides/cs/Program.cs)] +[!code-csharp[](../../samples/presentation/working_with_handout_master_slides/cs/Program.cs#snippet0)] ### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/presentation/working_with_handout_master_slides/vb/Program.vb)] +[!code-vb[](../../samples/presentation/working_with_handout_master_slides/vb/Program.vb#snippet0)] ## Generated PresentationML @@ -157,55 +157,41 @@ When the Open XML SDK code is run, the following XML is written to the PresentationML document referenced in the code. ```xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ``` ## See also diff --git a/docs/presentation/working-with-notes-slides.md b/docs/presentation/working-with-notes-slides.md index 1118f431..99f8c2d9 100644 --- a/docs/presentation/working-with-notes-slides.md +++ b/docs/presentation/working-with-notes-slides.md @@ -11,19 +11,21 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 01/16/2025 ms.localizationpriority: medium --- # Working with notes slides -This topic discusses the Open XML SDK for Office [NotesSlide](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.notesslide.aspx) class and how it relates to the +This topic discusses the Open XML SDK for Office class and how it relates to the Open XML File Format PresentationML schema. -------------------------------------------------------------------------------- + ## Notes Slides in PresentationML -The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification describes the Open XML PresentationML \ element + +The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification describes the Open XML PresentationML `` element used to represent notes slides in a PresentationML document as follows: This element specifies the existence of a notes slide along with its @@ -34,11 +36,11 @@ notes element. **Example**: Consider the following PresentationML notes slide: ```xml - - - … - - … + + + … + + … ``` @@ -47,199 +49,230 @@ slide with all of its parts. Notice the cSld element, which specifies the common elements that can appear on any slide type and then any elements specify additional non-common properties for this notes slide. -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] -The \ element is the root element of the PresentationML Notes +The `` element is the root element of the PresentationML Notes Slide part. For more information about the overall structure of the parts and elements that make up a PresentationML document, see [Structure of a PresentationML Document](structure-of-a-presentationml-document.md). -The following table lists the child elements of the \ element +The following table lists the child elements of the `` element used when working with notes slides and the Open XML SDK classes that correspond to them. -| **PresentationML Element** | **Open XML SDK Class** | -|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| -| \ | [ColorMapOverride](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.colormapoverride.aspx) | -| \ | [CommonSlideData](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.commonslidedata.aspx) | -| \ | [ExtensionListWithModification](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.extensionlistwithmodification.aspx) | +| **PresentationML Element** | **Open XML SDK Class** | +|----------------------------|-------------------------------------| +| `` | | +| `` | | +| `` | | -The following table from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification describes the attributes of the \ element. +The following table from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification describes the attributes of the `` element. -| **Attributes** | **Description** | -|-------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| showMasterPhAnim (Show Master Placeholder Animations) | Specifies whether or not to display animations on placeholders from the master slide.
The possible values for this attribute are defined by the W3C XML Schema **boolean** datatype. | -| showMasterSp (Show Master Shapes) | Specifies if shapes on the master slide should be shown on slides or not.
The possible values for this attribute are defined by the W3C XML Schema **boolean** datatype. | +| **Attributes** | **Description** | +|-------------------------------------------------------|---------------------| +| `showMasterPhAnim` (Show Master Placeholder Animations) | Specifies whether or not to display animations on placeholders from the master slide.

The possible values for this attribute are defined by the W3C XML Schema `boolean` datatype. | +| `showMasterSp` (Show Master Shapes) | Specifies if shapes on the master slide should be shown on slides or not.

The possible values for this attribute are defined by the W3C XML Schema `boolean` datatype. | -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] --------------------------------------------------------------------------------- + ## Open XML SDK NotesSlide Class -The OXML SDK **NotesSlide** class represents -the \ element defined in the Open XML File Format schema for -PresentationML documents. Use the **NotesSlide** class to manipulate individual -\ elements in a PresentationML document. -Classes that represent child elements of the \ element and that -are therefore commonly associated with the **NotesSlide** class are shown in the following list. +The OXML SDK `NotesSlide` class represents +the `` element defined in the Open XML File Format schema for +PresentationML documents. Use the `NotesSlide` class to manipulate individual +`` elements in a PresentationML document. -### ColorMapOverride Class +Classes that represent child elements of the `` element and that +are therefore commonly associated with the `NotesSlide` class are shown in the following list. -The **ColorMapOverride** class corresponds to -the \ element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification introduces the \ element: +- ### ColorMapOverride Class -This element provides a mechanism with which to override the color -schemes listed within the \ element. If the -\ child element is present, the color scheme defined -by the master is used. If the \ child element is -present, it defines a new color scheme specific to the parent notes -slide, presentation slide, or slide layout. + The `ColorMapOverride` class corresponds to + the `` element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] + specification introduces the `` element: -© ISO/IEC29500: 2008. + This element provides a mechanism with which to override the color + schemes listed within the `` element. If the + `` child element is present, the color scheme defined + by the master is used. If the `` child element is + present, it defines a new color scheme specific to the parent notes + slide, presentation slide, or slide layout. -### CommonSlideData Class +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] -The **CommonSlideData** class corresponds to -the \ element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification introduces the \ element: +- ### CommonSlideData Class -This element specifies a container for the type of slide information -that is relevant to all of the slide types. All slides share a common -set of properties that is independent of the slide type; the description -of these properties for any particular slide is stored within the -slide's \ container. Slide data specific to the slide type -indicated by the parent element is stored elsewhere. + The `CommonSlideData` class corresponds to + the `` element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] + specification introduces the `` element: -The actual data in \ describe only the particular parent slide; -it is only the type of information stored that is common across all -slides. + This element specifies a container for the type of slide information + that is relevant to all of the slide types. All slides share a common + set of properties that is independent of the slide type; the description + of these properties for any particular slide is stored within the + slide's `` container. Slide data specific to the slide type + indicated by the parent element is stored elsewhere. -© ISO/IEC29500: 2008. + The actual data in `` describe only the particular parent slide; + it is only the type of information stored that is common across all + slides. -### ExtensionListWithModification Class + © [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] -The **ExtensionListWithModification** class -corresponds to the \element. The following information from the -[ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification introduces the \ element: +- ### ExtensionListWithModification Class -This element specifies the extension list with modification ability -within which all future extensions of element type \ are defined. -The extension list along with corresponding future extensions is used to -extend the storage capabilities of the PresentationML framework. This -allows for various new kinds of data to be stored natively within the -framework. + The `ExtensionListWithModification` class + corresponds to the ``element. The following information from the + [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification introduces the `` element: -[Note: Using this extLst element allows the generating application to -store whether this extension property has been modified. end note] + This element specifies the extension list with modification ability + within which all future extensions of element type `` are defined. + The extension list along with corresponding future extensions is used to + extend the storage capabilities of the PresentationML framework. This + allows for various new kinds of data to be stored natively within the + framework. -© ISO/IEC29500: 2008. + [Note: Using this extLst element allows the generating application to + store whether this extension property has been modified. end note] + + © [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] --------------------------------------------------------------------------------- ## Working with the NotesSlide Class + As shown in the Open XML SDK code sample that follows, every instance of -the **NotesSlide** class is associated with an -instance of the [NotesSlidePart](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.notesslidepart.aspx) class, which represents a +the `NotesSlide` class is associated with an +instance of the class, which represents a notes slide part, one of the parts of a PresentationML presentation file package, and a part that is required for each notes slide in a -presentation file. Each **NotesSlide** class -instance may also be associated with an instance of the [NotesMaster](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.notesmaster.aspx) class, which in turn is +presentation file. Each `NotesSlide` class +instance may also be associated with an instance of the class, which in turn is associated with a similarly named presentation part, represented by the -[NotesMasterPart](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.notesmasterpart.aspx) class. + class. -The **NotesSlide** class, which represents the -\ element, is therefore also associated with a series of other -classes that represent the child elements of the \ element. +The `NotesSlide` class, which represents the +`` element, is therefore also associated with a series of other +classes that represent the child elements of the `` element. Among these classes, as shown in the following code sample, are the -**CommonSlideData** class and the **ColorMapOverride** class. The [ShapeTree](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.shapetree.aspx) class and the [Shape](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.shape.aspx) classes are in turn associated with -the **CommonSlideData** class. +`CommonSlideData` class and the `ColorMapOverride` class. The class and the classes are in turn associated with +the `CommonSlideData` class. -------------------------------------------------------------------------------- ## Open XML SDK Code Example -The following method adds a new notes slide part to an existing -presentation and creates an instance of an Open XML SDK**NotesSlide** class in the new notes slide part. The -**NotesSlide** class constructor creates -instances of the **CommonSlideData** class and -the **ColorMap** class. The **CommonSlideData** class constructor creates an -instance of the [ShapeTree](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.shapetree.aspx) class, whose constructor in turn -creates additional class instances: an instance of the [NonVisualGroupShapeProperties](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.nonvisualgroupshapeproperties.aspx) class, an -instance of the [GroupShapeProperties](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.groupshapeproperties.aspx) class, and an instance -of the [Shape](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.shape.aspx) class. -The namespace represented by the letter *P* in the code is the [DocumentFormat.OpenXml.Presentation](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.aspx) -namespace. +> In the following code snippets `P` represents the namespace and `D` represents the namespace. -### [C#](#tab/cs) -[!code-csharp[](../../samples/presentation/working_with_notes_slides/cs/Program.cs)] +In the snippet below, a presentation is opened with `Presentation.Open` and the first +is retrieved or added if the presentation does not already have a `SlidePart`. -### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/presentation/working_with_notes_slides/vb/Program.vb)] +### [C#](#tab/cs-0) +[!code-csharp[](../../samples/presentation/working_with_notes_slides/cs/Program.cs#snippet1)] +### [Visual Basic](#tab/vb-0) +[!code-vb[](../../samples/presentation/working_with_notes_slides/vb/Program.vb#snippet1)] +*** ---------------------------------------------------------------------------------- -## Generated PresentationML -When the Open XML SDK code is run, the following XML is written to -the PresentationML document referenced in the code. + +In this snippet the a `NoteSlide` is added to the `NoteSlidePart` if one does not already exist. +The `NotesSlide` class constructor creates instances of the `CommonSlideData` class. +The `CommonSlideData` class constructor creates an instance of the class, whose constructor in turn +creates additional class instances: an instance of the class, an +instance of the class, and an instance +of the class. + + +### [C#](#tab/cs-1) +[!code-csharp[](../../samples/presentation/working_with_notes_slides/cs/Program.cs#snippet2)] +### [Visual Basic](#tab/vb-1) +[!code-vb[](../../samples/presentation/working_with_notes_slides/vb/Program.vb#snippet2)] +*** + +The `Shape` constructor creates an instance of , , and classes along with their required child elements. The `TextBody` +contains the , that has a , which contains the text of the note. The slide part is then added to the notes slide part. + +### [C#](#tab/cs-2) +[!code-csharp[](../../samples/presentation/working_with_notes_slides/cs/Program.cs#snippet3)] +### [Visual Basic](#tab/vb-2) +[!code-vb[](../../samples/presentation/working_with_notes_slides/vb/Program.vb#snippet3)] +*** + +The notes slide part created with the code above contains the following XML ```xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + This is a test note! + + + + + + + ``` + +The following snippets add the required and if they are missing. + +### [C#](#tab/cs-3) +[!code-csharp[](../../samples/presentation/working_with_notes_slides/cs/Program.cs#snippet4)] +### [Visual Basic](#tab/vb-3) +[!code-vb[](../../samples/presentation/working_with_notes_slides/vb/Program.vb#snippet4)] +*** + +## Sample code + +The following is the complete code sample in both C\# and Visual Basic. + +### [C#](#tab/cs-4) +[!code-csharp[](../../samples/presentation/working_with_notes_slides/cs/Program.cs#snippet0)] +### [Visual Basic](#tab/vb-4) +[!code-vb[](../../samples/presentation/working_with_notes_slides/vb/Program.vb#snippet0)] +*** + -------------------------------------------------------------------------------- ## See also -[About the Open XML SDK for Office](../about-the-open-xml-sdk.md) +[About the Open XML SDK for Office](../about-the-open-xml-sdk.md) -[How to: Create a Presentation by Providing a File Name](how-to-create-a-presentation-document-by-providing-a-file-name.md) +[How to: Create a Presentation by Providing a File Name](how-to-create-a-presentation-document-by-providing-a-file-name.md) -[How to: Insert a new slide into a presentation](how-to-insert-a-new-slide-into-a-presentation.md) +[How to: Insert a new slide into a presentation](how-to-insert-a-new-slide-into-a-presentation.md) -[How to: Delete a slide from a presentation](how-to-delete-a-slide-from-a-presentation.md) +[How to: Delete a slide from a presentation](how-to-delete-a-slide-from-a-presentation.md) -[How to: Apply a theme to a presentation](how-to-apply-a-theme-to-a-presentation.md) +[How to: Apply a theme to a presentation](how-to-apply-a-theme-to-a-presentation.md) diff --git a/docs/presentation/working-with-presentation-slides.md b/docs/presentation/working-with-presentation-slides.md index 7ce19fef..ef029869 100644 --- a/docs/presentation/working-with-presentation-slides.md +++ b/docs/presentation/working-with-presentation-slides.md @@ -11,22 +11,21 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 09/20/2024 ms.localizationpriority: high --- # Working with presentation slides -This topic discusses the Open XML SDK for Office [Slide](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.slide.aspx) class and how it relates to the Open +This topic discusses the Open XML SDK for Office  class and how it relates to the Open XML File Format PresentationML schema. For more information about the overall structure of the parts and elements that make up a -PresentationML document, see [Structure of a -PresentationML document](structure-of-a-presentationml-document.md)**. +PresentationML document, see [Structure of a PresentationML document](structure-of-a-presentationml-document.md). --------------------------------------------------------------------------------- ## Presentation Slides in PresentationML -The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification describes the Open XML PresentationML \ element used +The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification describes the Open XML PresentationML `` element used to represent a presentation slide in a PresentationML document as follows: @@ -52,233 +51,169 @@ In the above example the order specified to present the slides is slide 4, then 3, 2, and finally 5. -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] -The \ element is the root element of the PresentationML Slide +The `` element is the root element of the PresentationML Slide part. For more information about the overall structure of the parts and elements that make up a PresentationML document, see [Structure of a PresentationML Document](structure-of-a-presentationml-document.md). -The following table lists the child elements of the \ element used +The following table lists the child elements of the `` element used when working with presentation slides and the Open XML SDK classes that correspond to them. | **PresentationML Element** | **Open XML SDK Class** | -|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| -| \ | [ColorMapOverride](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.colormapoverride.aspx) | -| \ | [CommonSlideData](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.commonslidedata.aspx) | -| \ | [ExtensionListWithModification](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.extensionlistwithmodification.aspx) | -| \ | [Timing](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.timing.aspx) | -| \ | [Transition](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.transition.aspx) | +|----------------------------|--------------------------------------------------------| +| `` | | +| `` | | +| `` | | +| `` | | +| `` | | -------------------------------------------------------------------------------- ## Open XML SDK Slide Class -The Open XML SDK**Slide** class represents the \ element +The Open XML SDK `Slide` class represents the `` element defined in the Open XML File Format schema for PresentationML documents. -Use the **Slide** object to manipulate -individual \ elements in a PresentationML document. +Use the `Slide` object to manipulate +individual `` elements in a PresentationML document. -Classes commonly associated with the **Slide** +Classes commonly associated with the `Slide` class are shown in the following sections. ### ColorMapOverride Class -The **ColorMapOverride** class corresponds to -the \ element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification introduces the \ element: +The `ColorMapOverride` class corresponds to +the `` element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification introduces the `` element: This element provides a mechanism with which to override the color -schemes listed within the \ element. If the -\ child element is present, the color scheme defined -by the master is used. If the \ child element is +schemes listed within the `` element. If the +`` child element is present, the color scheme defined +by the master is used. If the `` child element is present, it defines a new color scheme specific to the parent notes slide, presentation slide, or slide layout. -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] ### CommonSlideData Class -The **CommonSlideData** class corresponds to -the \ element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification introduces the \ element: +The `CommonSlideData` class corresponds to +the `` element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification introduces the `` element: This element specifies a container for the type of slide information that is relevant to all of the slide types. All slides share a common set of properties that is independent of the slide type; the description of these properties for any particular slide is stored within the -slide's \ container. Slide data specific to the slide type +slide's `` container. Slide data specific to the slide type indicated by the parent element is stored elsewhere. -The actual data in \ describe only the particular parent slide; +The actual data in `` describe only the particular parent slide; it is only the type of information stored that is common across all slides. -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] ### ExtensionListWithModification Class -The **ExtensionListWithModification** class -corresponds to the \element. The following information from the -[ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification introduces the \ element: +The `ExtensionListWithModification` class +corresponds to the `` element. The following information from the +[!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification introduces the `` element: This element specifies the extension list with modification ability -within which all future extensions of element type \ are defined. +within which all future extensions of element type `` are defined. The extension list along with corresponding future extensions is used to extend the storage capabilities of the PresentationML framework. This allows for various new kinds of data to be stored natively within the framework. -[Note: Using this extLst element allows the generating application to +[Note: Using this `extLst` element allows the generating application to store whether this extension property has been modified. end note] -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] ### Timing Class -The **Timing** class corresponds to the -\ element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification introduces the \ element: +The `Timing` class corresponds to the +`` element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification introduces the `` element: This element specifies the timing information for handling all animations and timed events within the corresponding slide. This -information is tracked via time nodes within the \ element. +information is tracked via time nodes within the `` element. More information on the specifics of these time nodes and how they are to be defined can be found within the Animation section of the PresentationML framework. -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] ### Transition Class -The **Transition** class corresponds to the -\ element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification introduces the \ element: +The `Transition` class corresponds to the +`` element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification introduces the `` element: This element specifies the kind of slide transition that should be used to transition to the current slide from the previous slide. That is, the transition information is stored on the slide that appears after the transition is complete. -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] -------------------------------------------------------------------------------- ## Working with the Slide Class + As shown in the Open XML SDK code example that follows, every instance -of the **Slide** class is associated with an -instance of the [SlidePart](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.slidepart.aspx) class, which represents a slide +of the `Slide` class is associated with an +instance of the class, which represents a slide part, one of the required parts of a PresentationML presentation file -package. Each instance of the **Slide** class -must also be associated with instances of the [SlideLayout](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.slidelayout.aspx) and [SlideMaster](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.slidemaster.aspx) classes, which are in turn +package. Each instance of the `Slide` class +must also be associated with instances of the and classes, which are in turn associated with similarly named required presentation parts, represented -by the [SlideLayoutPart](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.slidelayoutpart.aspx) and [SlideMasterPart](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.slidemasterpart.aspx) classes. +by the and classes. -The **Slide** class, which represents the -\ element, is therefore also associated with a series of other -classes that represent the child elements of the \ element. Among -these classes, as shown in the following code example, are the **CommonSlideData** class, the **ColorMapOverride** class, the [ShapeTree](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.shapetree.aspx) class, and the [Shape](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.shape.aspx) class. +The `Slide` class, which represents the +`` element, is therefore also associated with a series of other +classes that represent the child elements of the `` element. Among +these classes, as shown in the following code example, are the `CommonSlideData` class, the `ColorMapOverride` class, the class, and the class. -------------------------------------------------------------------------------- ## Open XML SDK Code Example -The following method from the article [How to: Create a presentation document by providing a file name](how-to-create-a-presentation-document-by-providing-a-file-name.md)** adds a new slide +The following method from the article [How to: Create a presentation document by providing a file name](how-to-create-a-presentation-document-by-providing-a-file-name.md) adds a new slide part to an existing presentation and creates an instance of the Open XML -SDK **Slide** class in the new slide part. -The **Slide** class constructor creates -instances of the **CommonSlideData** and **ColorMapOverride** classes. The **CommonSlideData** class constructor creates an -instance of the **ShapeTree** class, whose +SDK `Slide` class in the new slide part. +The `Slide` class constructor creates +instances of the `CommonSlideData` and `ColorMapOverride` classes. The `CommonSlideData` class constructor creates an +instance of the `ShapeTree` class, whose constructor, in turn, creates additional class instances: an instance of -the [NonVisualGroupShapeProperties](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.nonvisualgroupshapeproperties.aspx) class, the [GroupShapeProperties](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.groupshapeproperties.aspx) class, and the **Shape** class. +the class, the class, and the `Shape` class. All of these class instances and instances of the classes that represent -the child elements of the \ element are required to create the +the child elements of the `` element are required to create the minimum number of XML elements necessary to represent a new slide. -The namespace represented by the letter *P* in the code is the [DocumentFormat.OpenXml.Presentation](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.aspx) +The namespace represented by the letter *P* in the code is the namespace. ### [C#](#tab/cs-0) -```csharp - private static SlidePart CreateSlidePart(PresentationPart presentationPart) - { - SlidePart slidePart1 = presentationPart.AddNewPart("rId2"); - slidePart1.Slide = new Slide( - new CommonSlideData( - new ShapeTree( - new P.NonVisualGroupShapeProperties( - new P.NonVisualDrawingProperties() { Id = (UInt32Value)1U, Name = "" }, - new P.NonVisualGroupShapeDrawingProperties(), - new ApplicationNonVisualDrawingProperties()), - new GroupShapeProperties(new TransformGroup()), - new P.Shape( - new P.NonVisualShapeProperties( - new P.NonVisualDrawingProperties() { Id = (UInt32Value)2U, Name = "Title 1" }, - new P.NonVisualShapeDrawingProperties(new ShapeLocks() { NoGrouping = true }), - new ApplicationNonVisualDrawingProperties(new PlaceholderShape())), - new P.ShapeProperties(), - new P.TextBody( - new BodyProperties(), - new ListStyle(), - new Paragraph(new EndParagraphRunProperties() { Language = "en-US" }))))), - new ColorMapOverride(new MasterColorMapping())); - return slidePart1; - } -``` - +[!code-csharp[](../../samples/presentation/create_by_providing_a_file_name/cs/Program.cs#snippet102)] ### [Visual Basic](#tab/vb-0) -```vb - Private Shared Function CreateSlidePart(ByVal presentationPart As PresentationPart) As SlidePart - Dim slidePart1 As SlidePart = presentationPart.AddNewPart(Of SlidePart)("rId2") - slidePart1.Slide = New Slide(New CommonSlideData(New ShapeTree(New P.NonVisualGroupShapeProperties(New P.NonVisualDrawingProperties() With { _ - .Id = CType(1UI, UInt32Value), _ - .Name = "" _ - }, New P.NonVisualGroupShapeDrawingProperties(), New ApplicationNonVisualDrawingProperties()), New GroupShapeProperties(New TransformGroup()), _ - New P.Shape(New P.NonVisualShapeProperties(New P.NonVisualDrawingProperties() With { _ - .Id = CType(2UI, UInt32Value), _ - .Name = "Title 1" _ - }, New P.NonVisualShapeDrawingProperties(New ShapeLocks() With { _ - .NoGrouping = True _ - }), New ApplicationNonVisualDrawingProperties(New PlaceholderShape())), New P.ShapeProperties(), New P.TextBody(New BodyProperties(), _ - New ListStyle(), New Paragraph(New EndParagraphRunProperties() With { _ - .Language = "en-US" _ - }))))), New ColorMapOverride(New MasterColorMapping())) - Return slidePart1 - End Function -``` +[!code-vb[](../../samples/presentation/create_by_providing_a_file_name/vb/Program.vb#snippet102)] *** To add another shape to the shape tree and, hence, to the slide, -instantiate a second **Shape** object by +instantiate a second `Shape` object by passing an additional parameter that contains the following code to the -**ShapeTree** constructor. +`ShapeTree` constructor. ### [C#](#tab/cs-1) -```csharp - new P.Shape( - new P.NonVisualShapeProperties( - new P.NonVisualDrawingProperties() { Id = (UInt32Value)2U, Name = "Title 1" }, - new P.NonVisualShapeDrawingProperties(new ShapeLocks() { NoGrouping = true }), - new ApplicationNonVisualDrawingProperties(new PlaceholderShape())), - new P.ShapeProperties(), - new P.TextBody( - new BodyProperties(), - new ListStyle(), - new Paragraph(new EndParagraphRunProperties() { Language = "en-US" }))) -``` - +[!code-csharp[](../../samples/presentation/create_by_providing_a_file_name/cs/Program.cs#snippet103)] ### [Visual Basic](#tab/vb-1) -```vb - New P.Shape(New P.NonVisualShapeProperties(New P.NonVisualDrawingProperties() With { _ - .Id = CType(2UI, UInt32Value), _ - .Name = "Title 1" _ - }, New P.NonVisualShapeDrawingProperties(New ShapeLocks() With { _ - .NoGrouping = True _ - }), New ApplicationNonVisualDrawingProperties(New PlaceholderShape())), New P.ShapeProperties(), New P.TextBody(New BodyProperties(), _ - New ListStyle(), New Paragraph(New EndParagraphRunProperties() With { _ - .Language = "en-US" }))) -``` +[!code-vb[](../../samples/presentation/create_by_providing_a_file_name/vb/Program.vb#snippet103)] *** @@ -289,7 +224,7 @@ is written to the PresentationML document file referenced in the code. ```xml - + @@ -298,13 +233,13 @@ is written to the PresentationML document file referenced in the code. - + - + @@ -312,9 +247,9 @@ is written to the PresentationML document file referenced in the code. - - - + + + @@ -322,7 +257,7 @@ is written to the PresentationML document file referenced in the code. - + ``` diff --git a/docs/presentation/working-with-presentations.md b/docs/presentation/working-with-presentations.md index 6cd68f78..973c4111 100644 --- a/docs/presentation/working-with-presentations.md +++ b/docs/presentation/working-with-presentations.md @@ -11,22 +11,21 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 09/19/2024 ms.localizationpriority: medium --- # Working with presentations -This topic discusses the Open XML SDK for Office [Presentation](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.presentation.aspx) class and how it relates to +This topic discusses the Open XML SDK for Office  class and how it relates to the Open XML File Format PresentationML schema. For more information about the overall structure of the parts and elements that make up a -PresentationML document, see [Structure of a -PresentationML document](structure-of-a-presentationml-document.md). +PresentationML document, see [Structure of a PresentationML document](structure-of-a-presentationml-document.md). --------------------------------------------------------------------------------- ## Presentations in PresentationML -The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification describes the Open XML PresentationML \ +The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification describes the Open XML PresentationML `` element used to represent a presentation in a PresentationML document as follows: @@ -55,53 +54,53 @@ size and default text styles. ``` -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] -The \ element typically contains child elements that list +The `` element typically contains child elements that list slide masters, slides, and custom slide shows contained within the presentation. In addition, it also commonly contains elements that specify other properties of the presentation, such as slide size, notes size, and default text styles. -The \ element is the root element of the PresentationML +The `` element is the root element of the PresentationML Presentation part. For more information about the overall structure of the parts and elements that make up a PresentationML document, see [Structure of a PresentationML Document](structure-of-a-presentationml-document.md). The following table lists some of the most common child elements of the -\ element used when working with presentations and the +`` element used when working with presentations and the Open XML SDK classes that correspond to them. | **PresentationML Element** | **Open XML SDK Class** | |----------------------------|-------------------------------------------------------------------------------------------------------------------------------------| -| \ | [SlideMasterIdList](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.slidemasteridlist.aspx) | -| \ | [SlideMasterId](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.slidemasterid.aspx) | -| \ | [SlideIdList](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.slideidlist.aspx) | -| \ | [SlideId](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.slideid.aspx) | -| \ | [NotesMasterIdList](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.notesmasteridlist.aspx) | -| \ | [HandoutMasterIdList](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.handoutmasteridlist.aspx) | -| \ | [CustomShowList](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.customshowlist.aspx) | -| \ | [SlideSize](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.slidesize.aspx) | -| \ | [NotesSize](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.notessize.aspx) | -| \ | [DefaultTextStyle](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.defaulttextstyle.aspx) | +| `` | | +| `` | | +| `` | | +| `` | | +| `` | | +| `` | | +| `` | | +| `` | | +| `` | | +| `` | | -------------------------------------------------------------------------------- ## Open XML SDK Presentation Class -The Open XML SDK**Presentation** class -represents the \ element defined in the Open XML File -Format schema for PresentationML documents. Use the **Presentation** class to manipulate an individual -\ element in a PresentationML document. +The Open XML SDK `Presentation` class +represents the `` element defined in the Open XML File +Format schema for PresentationML documents. Use the `Presentation` class to manipulate an individual +`` element in a PresentationML document. -Classes commonly associated with the **Presentation** class are shown in the following +Classes commonly associated with the `Presentation` class are shown in the following sections. ### SlideMasterIdList Class All slides that share the same master inherit the same layout from that -master. The **SlideMasterIdList** class -corresponds to the \ element. The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification describes the Open XML PresentationML \ +master. The `SlideMasterIdList` class +corresponds to the `` element. The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification describes the Open XML PresentationML `` element used to represent a slide master ID list in a PresentationML document as follows: @@ -110,13 +109,13 @@ slide master slides that are available within the corresponding presentation. A slide master is a slide that is specifically designed to be a template for all related child layout slides. -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] ### SlideMasterId Class -The **SlideMasterId** class corresponds to the -\ element. The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification describes the Open XML PresentationML \ +The `SlideMasterId` class corresponds to the +`` element. The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification describes the Open XML PresentationML `` element used to represent a slide master ID in a PresentationML document as follows: @@ -139,13 +138,13 @@ embedTrueTypeFonts="1"> ``` -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] ### SlideIdList Class -The **SlideIdList** class corresponds to the -\ element. The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification describes the Open XML PresentationML \ element +The `SlideIdList` class corresponds to the +`` element. The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification describes the Open XML PresentationML `` element used to represent a slide ID list in a PresentationML document as follows: @@ -154,13 +153,13 @@ slides that are available within the corresponding presentation. A slide contains the information that is specific to a single slide such as slide-specific shape and text information. -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] ### SlideId Class -The **SlideId** class corresponds to the -\ element. The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification describes the Open XML PresentationML \ element +The `SlideId` class corresponds to the +`` element. The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification describes the Open XML PresentationML `` element used to represent a slide ID in a PresentationML document as follows: This element specifies a presentation slide that is available within the @@ -172,8 +171,7 @@ information. a presentation ```xml - + … @@ -186,13 +184,13 @@ embedTrueTypeFonts="1"> ``` -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] ### NotesMasterIdList Class -The **NotesMasterIdList** class corresponds to -the \ element. The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification describes the Open XML PresentationML \ +The `NotesMasterIdList` class corresponds to +the `` element. The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification describes the Open XML PresentationML `` element used to represent a notes master ID list in a PresentationML document as follows: @@ -201,14 +199,14 @@ notes master slides that are available within the corresponding presentation. A notes master is a slide that is specifically designed for the printing of the slide along with any attached notes. -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] ### HandoutMasterIdList Class -The **HandoutMasterIdList** class corresponds -to the \ element. The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) +The `HandoutMasterIdList` class corresponds +to the `` element. The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification describes the Open XML PresentationML -\ element used to represent a handout master ID +`` element used to represent a handout master ID list in a PresentationML document as follows: This element specifies a list of identification information for the @@ -216,13 +214,13 @@ handout master slides that are available within the corresponding presentation. A handout master is a slide that is specifically designed for printing as a handout. -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] ### CustomShowList Class -The **CustomShowList** class corresponds to the -\ element. The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification describes the Open XML PresentationML \ +The `CustomShowList` class corresponds to the +`` element. The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification describes the Open XML PresentationML `` element used to represent a custom show list in a PresentationML document as follows: @@ -231,13 +229,13 @@ within the corresponding presentation. A custom show is a defined slide sequence that allows for the displaying of the slides with the presentation in any arbitrary order. -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] ### SlideSize Class -The **SlideSize** class corresponds to the -\ element. The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification describes the Open XML PresentationML \ element +The `SlideSize` class corresponds to the +`` element. The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification describes the Open XML PresentationML `` element used to represent presentation slide size in a PresentationML document as follows: @@ -258,13 +256,13 @@ embedTrueTypeFonts="1"> ``` -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] ### NotesSize Class -The **NotesSize** class corresponds to the -\ element. The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification describes the Open XML PresentationML \ element +The `NotesSize` class corresponds to the +`` element. The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification describes the Open XML PresentationML `` element used to represent notes slide size in a PresentationML document as follows: @@ -288,13 +286,13 @@ embedTrueTypeFonts="1"> ``` -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] ### DefaultTextStyle Class -The DefaultTextStyle class corresponds to the \ -element. The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification describes the Open XML PresentationML \ +The `DefaultTextStyle` class corresponds to the `` +element. The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification describes the Open XML PresentationML `` element used to represent default text style in a PresentationML document as follows: @@ -304,47 +302,49 @@ when inserting a new slide if that slide is not associated with a master slide or if no styling information has been otherwise specified for the text within the presentation slide. -© ISO/IEC29500: 2008. +© [!include[ISO/IEC 29500 version](../includes/iso-iec-29500-version.md)] -------------------------------------------------------------------------------- ## Working with the Presentation Class + As shown in the Open XML SDK code example that follows, every instance -of the **Presentation** class is associated -with an instance of the [PresentationPart](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationpart.aspx) class, which represents a +of the `Presentation` class is associated +with an instance of the class, which represents a presentation part, one of the required parts of a PresentationML presentation file package. -The **Presentation** class, which represents -the \ element, is therefore also associated with a series +The `Presentation` class, which represents +the `` element, is therefore also associated with a series of other classes that represent the child elements of the -\ element. Among these classes, as shown in the following -code example, are the **SlideMasterIdList**, -**SlideIdList**, **SlideSize**, **NotesSize**, and **DefaultTextStyle** classes. +`` element. Among these classes, as shown in the following +code example, are the `SlideMasterIdList`, +`SlideIdList`, `SlideSize`, `NotesSize`, and `DefaultTextStyle` classes. -------------------------------------------------------------------------------- ## Open XML SDK Code Example -The following code example from the article [How to: Create a presentation document by providing a file name](how-to-create-a-presentation-document-by-providing-a-file-name.md) uses the [Create(String, PresentationDocumentType)](https://msdn.microsoft.com/library/office/cc535977.aspx) -method of the [PresentationDocument](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationdocument.aspx) class of the Open XML + +The following code example from the article [How to: Create a presentation document by providing a file name](how-to-create-a-presentation-document-by-providing-a-file-name.md) uses the +method of the class of the Open XML SDK to create an instance of that same class that has the specified -name and file path. Then it uses the [AddPresentationPart()](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationdocument.addpresentationpart.aspx) method to add an -instance of the [PresentationPart](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.presentationpart.aspx) class to the document -file. Next, it creates an instance of the [Presentation](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.presentation.aspx) class that represents the -presentation. It passes a reference to the **PresentationPart** class instance to the -**CreatePresentationParts** procedure, which creates the other required -parts of the presentation file. The **CreatePresentation** procedure -cleans up by closing the **PresentationDocument** class instance that it +name and file path. Then it uses the method to add an +instance of the class to the document +file. Next, it creates an instance of the class that represents the +presentation. It passes a reference to the `PresentationPart` class instance to the +`CreatePresentationParts` procedure, which creates the other required +parts of the presentation file. The `CreatePresentation` procedure +cleans up by closing the `PresentationDocument` class instance that it opened previously. -The **CreatePresentationParts** procedure creates instances of the **SlideMasterIdList**, **SlideIdList**, **SlideSize**, **NotesSize**, and **DefaultTextStyle** classes and appends them to the +The `CreatePresentationParts` procedure creates instances of the `SlideMasterIdList`, `SlideIdList`, `SlideSize`, `NotesSize`, and `DefaultTextStyle` classes and appends them to the presentation. ### [C#](#tab/cs) -[!code-csharp[](../../samples/presentation/working_with_presentations/cs/Program.cs)] +[!code-csharp[](../../samples/presentation/create_by_providing_a_file_name/cs/Program.cs#snippet101)] ### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/presentation/working_with_presentations/vb/Program.vb)] +[!code-vb[](../../samples/presentation/create_by_providing_a_file_name/vb/Program.vb#snippet101)] --------------------------------------------------------------------------------- ## Resulting PresentationML @@ -353,12 +353,12 @@ PresentationML document referenced in the code. ```xml - + - + - + diff --git a/docs/presentation/working-with-slide-layouts.md b/docs/presentation/working-with-slide-layouts.md index bd322378..2b8d96ec 100644 --- a/docs/presentation/working-with-slide-layouts.md +++ b/docs/presentation/working-with-slide-layouts.md @@ -11,104 +11,104 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 09/18/2024 ms.localizationpriority: medium --- # Working with slide layouts -This topic discusses the Open XML SDK for Office [SlideLayout](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.slidelayout.aspx) class and how it relates to the Open XML File Format PresentationML schema. +This topic discusses the Open XML SDK for Office class and how it relates to the Open XML File Format PresentationML schema. ## Slide Layouts in PresentationML -The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification describes the Open XML PresentationML \ element used to represent slide layouts in a PresentationML document as follows: +The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification describes the Open XML PresentationML `` element used to represent slide layouts in a PresentationML document as follows: This element specifies an instance of a slide layout. The slide layout contains in essence a template slide design that can be applied to any existing slide. When applied to an existing slide all corresponding content should be mapped to the new slide layout. -The \ element is the root element of the PresentationML +The `` element is the root element of the PresentationML Slide Layout part. For more information about the overall structure of the parts and elements that make up a PresentationML document, see [Structure of a PresentationML Document](structure-of-a-presentationml-document.md). -The following table lists the child elements of the \ +The following table lists the child elements of the `` element used when working with slide layouts and the Open XML SDK classes that correspond to them. -| **PresentationML Element** | **Open XML SDK Class** | -|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| -| \ | [ColorMapOverride](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.colormapoverride.aspx) | -| \ | [CommonSlideData](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.commonslidedata.aspx) | -| \ | [ExtensionListWithModification](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.extensionlistwithmodification.aspx) | -| \ | [HeaderFooter](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.headerfooter.aspx) | -| \ | [Timing](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.timing.aspx) | -| \ | [Transition](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.transition.aspx) | +| **PresentationML Element** | **Open XML SDK Class** | +|----------------------------|-------------------------------------| +| `` | | +| `` | | +| `` | | +| `` | | +| `` | | +| `` | | -The following table from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification describes the attributes of the \ element. +The following table from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification describes the attributes of the `` element. -| **Attributes** | **Description** | -|-------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| matchingName (Matching Name) | Specifies a name to be used in place of the name attribute within the cSld element. This is used for layout matching in response to layout changes and template applications.
The possible values for this attribute are defined by the W3C XML Schema **string** datatype. | -| preserve (Preserve Slide Layout) | Specifies whether the corresponding slide layout is deleted when all the slides that follow that layout are deleted. If this attribute is not specified then a value of **false** should be assumed by the generating application. This would mean that the slide would in fact be deleted if no slides within the presentation were related to it.
The possible values for this attribute are defined by the W3C XML Schema **boolean** datatype. | -| showMasterPhAnim (Show Master Placeholder Animations) | Specifies whether or not to display animations on placeholders from the master slide.
The possible values for this attribute are defined by the W3C XML Schema **boolean** datatype. | -| showMasterSp (Show Master Shapes) | Specifies if shapes on the master slide should be shown on slides or not.
The possible values for this attribute are defined by the W3C XML Schema **boolean** datatype. | -| type (Slide Layout Type) | Specifies the slide layout type that is used by this slide.
The possible values for this attribute are defined by the ST_SlideLayoutType simple type (§19.7.15). | -| userDrawn (Is User Drawn) | Specifies if the corresponding object has been drawn by the user and should thus not be deleted. This allows for the flagging of slides that contain user drawn data.
The possible values for this attribute are defined by the W3C XML Schema **boolean** datatype. | +| **Attributes** | **Description** | +| -----------------|-------------------| +| matchingName (Matching Name) | Specifies a name to be used in place of the name attribute within the cSld element. This is used for layout matching in response to layout changes and template applications.

The possible values for this attribute are defined by the W3C XML Schema `string` datatype. | +| preserve (Preserve Slide Layout) | Specifies whether the corresponding slide layout is deleted when all the slides that follow that layout are deleted. If this attribute is not specified then a value of `false` should be assumed by the generating application. This would mean that the slide would in fact be deleted if no slides within the presentation were related to it.

The possible values for this attribute are defined by the W3C XML Schema `boolean` datatype. | +| showMasterPhAnim (Show Master Placeholder Animations) | Specifies whether or not to display animations on placeholders from the master slide.

The possible values for this attribute are defined by the W3C XML Schema `boolean` datatype. | +| showMasterSp (Show Master Shapes) | Specifies if shapes on the master slide should be shown on slides or not.

The possible values for this attribute are defined by the W3C XML Schema `boolean` datatype. | +| type (Slide Layout Type) | Specifies the slide layout type that is used by this slide.

The possible values for this attribute are defined by the ST_SlideLayoutType simple type (§19.7.15). | +| userDrawn (Is User Drawn) | Specifies if the corresponding object has been drawn by the user and should thus not be deleted. This allows for the flagging of slides that contain user drawn data.

The possible values for this attribute are defined by the W3C XML Schema `boolean` datatype. | ## The Open XML SDK SlideLayout Class -The OXML SDK **SlideLayout** class represents -the \ element defined in the Open XML File Format schema for -PresentationML documents. Use the **SlideLayout** class to manipulate individual -\ elements in a PresentationML document. +The OXML SDK `SlideLayout` class represents +the `` element defined in the Open XML File Format schema for +PresentationML documents. Use the `SlideLayout` class to manipulate individual +`` elements in a PresentationML document. -Classes that represent child elements of the \ element and -that are therefore commonly associated with the **SlideLayout** class are shown in the following +Classes that represent child elements of the `` element and +that are therefore commonly associated with the `SlideLayout` class are shown in the following list. ### ColorMapOverride Class -The **ColorMapOverride** class corresponds to -the \ element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification introduces the \ element: +The `ColorMapOverride` class corresponds to +the `` element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification introduces the `` element: This element provides a mechanism with which to override the color -schemes listed within the \ element. If the -\ child element is present, the color scheme defined -by the master is used. If the \ child element is +schemes listed within the `` element. If the +`` child element is present, the color scheme defined +by the master is used. If the `` child element is present, it defines a new color scheme specific to the parent notes slide, presentation slide, or slide layout. ### CommonSlideData Class -The **CommonSlideData** class corresponds to -the \ element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification introduces the \ element: +The `CommonSlideData` class corresponds to +the `` element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification introduces the `` element: This element specifies a container for the type of slide information that is relevant to all of the slide types. All slides share a common set of properties that is independent of the slide type; the description of these properties for any particular slide is stored within the -slide's \ container. Slide data specific to the slide type +slide's `` container. Slide data specific to the slide type indicated by the parent element is stored elsewhere. -The actual data in \ describe only the particular parent slide; +The actual data in `` describe only the particular parent slide; it is only the type of information stored that is common across all slides. ### ExtensionListWithModification Class -The **ExtensionListWithModification** class -corresponds to the \element. The following information from the -[ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification introduces the \ element: +The `ExtensionListWithModification` class +corresponds to the ``element. The following information from the +[!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification introduces the `` element: This element specifies the extension list with modification ability -within which all future extensions of element type \ are defined. +within which all future extensions of element type `` are defined. The extension list along with corresponding future extensions is used to extend the storage capabilities of the PresentationML framework. This allows for various new kinds of data to be stored natively within the @@ -119,9 +119,9 @@ framework. ### HeaderFooter Class -The **HeaderFooter** class corresponds to the -\ element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification introduces the \ element: +The `HeaderFooter` class corresponds to the +`` element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification introduces the `` element: This element specifies the header and footer information for a slide. Headers and footers consist of placeholders for text that should be @@ -130,51 +130,52 @@ slide numbering, and custom header and footer text. ### Timing Class -The **Timing** class corresponds to the -\ element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification introduces the \ element: +The `Timing` class corresponds to the +`` element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification introduces the `` element: This element specifies the timing information for handling all animations and timed events within the corresponding slide. This -information is tracked via time nodes within the \ element. +information is tracked via time nodes within the `` element. More information on the specifics of these time nodes and how they are to be defined can be found within the Animation section of the PresentationML framework. ### Transition Class -The **Transition** class corresponds to the \ element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification introduces the \ element: +The `Transition` class corresponds to the `` element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification introduces the `` element: This element specifies the kind of slide transition that should be used to transition to the current slide from the previous slide. That is, the transition information is stored on the slide that appears after the transition is complete. ## Working with the SlideLayout Class As shown in the Open XML SDK code sample that follows, every instance of -the **SlideLayout** class is associated with an -instance of the [SlideLayoutPart](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.slidelayoutpart.aspx) class, which represents a +the `SlideLayout` class is associated with an +instance of the class, which represents a slide layout part, one of the required parts of a PresentationML -presentation file package. Each **SlideLayout** -class instance must also be associated with instances of the [SlideMaster](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.slidemaster.aspx) and [Slide](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.slide.aspx) classes, which are in turn associated +presentation file package. Each `SlideLayout` +class instance must also be associated with instances of the and classes, which are in turn associated with similarly named required presentation parts, represented by the -[SlideMasterPart](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.slidemasterpart.aspx) and [SlidePart](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.slidepart.aspx)classes. + and classes. -The **SlideLayout** class, which represents the -\ element, is therefore also associated with a series of -other classes that represent the child elements of the \ +The `SlideLayout` class, which represents the +`` element, is therefore also associated with a series of +other classes that represent the child elements of the `` element. Among these classes, as shown in the following code sample, are -the **CommonSlideData** class, the **ColorMapOverride** class, the [ShapeTree](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.shapetree.aspx) class, and the [Shape](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.shape.aspx) class. +the `CommonSlideData` class, the `ColorMapOverride` class, the class, and the class. ## Open XML SDK Code Example -The following method from the article [How to: Create a presentation document by providing a file name](how-to-create-a-presentation-document-by-providing-a-file-name.md) adds a new slide layout part to an existing presentation and creates an instance of an Open XML SDK**SlideLayout** class in the new slide layout part. The **SlideLayout** class constructor creates instances of the **CommonSlideData** class and the **ColorMapOverride** class. The **CommonSlideData** class constructor creates an instance of the [ShapeTree](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.shapetree.aspx) class, whose constructor in turn creates additional class instances: an instance of the [NonVisualGroupShapeProperties (https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.nonvisualgroupshapeproperties.aspx) class, an instance of the [GroupShapeProperties](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.groupshapeproperties.aspx) class, and an instance of the [Shape](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.shape.aspx) class. +The following method from the article [How to: Create a presentation document by providing a file name](how-to-create-a-presentation-document-by-providing-a-file-name.md) adds a new slide layout part to an existing presentation and creates an instance of an Open XML SDK `SlideLayout` class in the new slide layout part. The `SlideLayout` class constructor creates instances of the `CommonSlideData` class and the `ColorMapOverride` class. The `CommonSlideData` class constructor creates an instance of the class, whose constructor in turn creates additional class instances: an instance of the class, an instance of the class, and an instance of the class. -The namespace represented by the letter *P* in the code is the [DocumentFormat.OpenXml.Presentation (https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.aspx) namespace. +The namespace represented by the letter *P* in the code is the namespace. ### [C#](#tab/cs) -[!code-csharp[](../../samples/presentation/working_with_slide_layouts/cs/Program.cs)] +[!code-csharp[](../../samples/presentation/create_by_providing_a_file_name/cs/Program.cs#snippet100)] ### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/presentation/working_with_slide_layouts/vb/Program.vb)] +[!code-vb[](../../samples/presentation/create_by_providing_a_file_name/vb/Program.vb#snippet100)] +*** ## Generated PresentationML @@ -182,7 +183,7 @@ When the Open XML SDK code is run, the following XML is written to the Presentat ```xml - + @@ -192,7 +193,7 @@ When the Open XML SDK code is run, the following XML is written to the Presentat - + @@ -200,7 +201,7 @@ When the Open XML SDK code is run, the following XML is written to the Presentat name="" /> + xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" /> @@ -208,9 +209,9 @@ When the Open XML SDK code is run, the following XML is written to the Presentat - - - + + + @@ -218,7 +219,7 @@ When the Open XML SDK code is run, the following XML is written to the Presentat - + ``` @@ -226,5 +227,7 @@ When the Open XML SDK code is run, the following XML is written to the Presentat ## See also [About the Open XML SDK for Office](../about-the-open-xml-sdk.md) + [How to: Create a Presentation by Providing a File Name](how-to-create-a-presentation-document-by-providing-a-file-name.md) + [How to: Apply a theme to a presentation](how-to-apply-a-theme-to-a-presentation.md) diff --git a/docs/presentation/working-with-slide-masters.md b/docs/presentation/working-with-slide-masters.md index d54e70af..b6e724ee 100644 --- a/docs/presentation/working-with-slide-masters.md +++ b/docs/presentation/working-with-slide-masters.md @@ -10,72 +10,72 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 09/17/2024 ms.localizationpriority: medium --- # Working with slide masters -This topic discusses the Open XML SDK for Office **[SlideMaster](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.slidemaster.aspx)** class and how it relates to the Open XML File Format PresentationML schema. +This topic discusses the Open XML SDK for Office class and how it relates to the Open XML File Format PresentationML schema. ## Slide Masters in PresentationML -The [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification describes the Open XML PresentationML \ element used to represent slide layouts in a PresentationML document as follows. +The [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification describes the Open XML PresentationML `` element used to represent slide layouts in a PresentationML document as follows. This element specifies an instance of a slide master slide. Within a slide master slide are contained all elements that describe the objects and their corresponding formatting for within a presentation slide. Within a slide master slide are two main elements. The cSld element specifies the common slide elements such as shapes and their attached text bodies. Then the txStyles element specifies the formatting for the text within each of these shapes. The other properties within a slide master slide specify other properties for within a presentation slide such as color information, headers and footers, as well as timing and transition information for all corresponding presentation slides. -The \ element is the root element of the PresentationML Slide Master part. For more information about the overall structure of the parts and elements that make up a PresentationML document, see [Structure of a PresentationML Document](structure-of-a-presentationml-document.md). +The `` element is the root element of the PresentationML Slide Master part. For more information about the overall structure of the parts and elements that make up a PresentationML document, see [Structure of a PresentationML Document](structure-of-a-presentationml-document.md). -The following table lists the child elements of the \ element used when working with slide masters and the Open XML SDK classes that correspond to them. +The following table lists the child elements of the `` element used when working with slide masters and the Open XML SDK classes that correspond to them. | **PresentationML Element** | **Open XML SDK Class** | |:---------------------------|:---------------------------------------------------------------------------------------------------------------------------| -| \ | [ColorMap](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.colormap.aspx) | -| \ | [CommonSlideData](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.commonslidedata.aspx) | -| \ | [ExtensionListWithModification](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.extensionlistwithmodification.aspx) | -| \ | [HeaderFooter](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.headerfooter.aspx) | -| \ | [SlideLayoutIdList](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.slidelayoutidlist.aspx) | -| \ | [Timing](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.timing.aspx) | -| \ | [Transition](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.transition.aspx) | -| \ | [TextStyles](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.textstyles.aspx) | - -The following table from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) -specification describes the attributes of the \ element. +| `` | | +| `` | | +| `` | | +| `` | | +| `` | | +| `` | | +| `` | | +| `` | | + +The following table from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] +specification describes the attributes of the `` element. | **Attributes** | **Description** | |----------------------------|----------------------------------------------------| -| preserve (Preserve Slide Master) | Specifies whether the corresponding slide layout is deleted when all the slides that follow that layout are deleted. If this attribute is not specified then a value of **false** should be assumed by the generating application. This would mean that the slide would in fact be deleted if no slides within the presentation were related to it.
The possible values for this attribute are defined by the W3C XML Schema **Boolean** data type. | +| preserve (Preserve Slide Master) | Specifies whether the corresponding slide layout is deleted when all the slides that follow that layout are deleted. If this attribute is not specified then a value of `false` should be assumed by the generating application. This would mean that the slide would in fact be deleted if no slides within the presentation were related to it.
The possible values for this attribute are defined by the W3C XML Schema `Boolean` data type. | ## Open XML SDK SlideMaster Class -The Open XML SDK**SlideMaster** class -represents the \ element defined in the Open XML File Format -schema for PresentationML documents. Use the **SlideMaster** class to manipulate individual -\ elements in a PresentationML document. +The Open XML SDK`SlideMaster` class +represents the `` element defined in the Open XML File Format +schema for PresentationML documents. Use the `SlideMaster` class to manipulate individual +`` elements in a PresentationML document. -Classes that represent child elements of the \ element and -that are therefore commonly associated with the **SlideMaster** class are shown in the following +Classes that represent child elements of the `` element and +that are therefore commonly associated with the `SlideMaster` class are shown in the following list. ### ColorMapOverride Class -The **ColorMapOverride** class corresponds to the \ element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification introduces the \ element: +The `ColorMapOverride` class corresponds to the `` element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification introduces the `` element: -This element provides a mechanism with which to override the color schemes listed within the \ element. If the \ child element is present, the color scheme defined by the master is used. If the \ child element is present, it defines a new color scheme specific to the parent notes slide, presentation slide, or slide layout. +This element provides a mechanism with which to override the color schemes listed within the `` element. If the `` child element is present, the color scheme defined by the master is used. If the `` child element is present, it defines a new color scheme specific to the parent notes slide, presentation slide, or slide layout. ### CommonSlideData Class -The **CommonSlideData** class corresponds to the \ element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification introduces the \ element: +The `CommonSlideData` class corresponds to the `` element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification introduces the `` element: -This element specifies a container for the type of slide information that is relevant to all of the slide types. All slides share a common set of properties that is independent of the slide type; the description of these properties for any particular slide is stored within the slide's \ container. Slide data specific to the slide type indicated by the parent element is stored elsewhere. +This element specifies a container for the type of slide information that is relevant to all of the slide types. All slides share a common set of properties that is independent of the slide type; the description of these properties for any particular slide is stored within the slide's `` container. Slide data specific to the slide type indicated by the parent element is stored elsewhere. -The actual data in \ describe only the particular parent slide; it is only the type of information stored that is common across all slides. +The actual data in `` describe only the particular parent slide; it is only the type of information stored that is common across all slides. ### ExtensionListWithModification Class -The **ExtensionListWithModification** class corresponds to the \element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification introduces the \ element: +The `ExtensionListWithModification` class corresponds to the ``element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification introduces the `` element: -This element specifies the extension list with modification ability within which all future extensions of element type \ are defined. The extension list along with corresponding future extensions is used to extend the storage capabilities of the PresentationML framework. This allows for various new kinds of data to be stored natively within the +This element specifies the extension list with modification ability within which all future extensions of element type `` are defined. The extension list along with corresponding future extensions is used to extend the storage capabilities of the PresentationML framework. This allows for various new kinds of data to be stored natively within the framework. > [!NOTE] @@ -83,31 +83,31 @@ framework. ### HeaderFooter Class -The **HeaderFooter** class corresponds to the \ element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification introduces the \ element: +The `HeaderFooter` class corresponds to the `` element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification introduces the `` element: This element specifies the header and footer information for a slide. Headers and footers consist of placeholders for text that should be consistent across all slides and slide types, such as a date and time, slide numbering, and custom header and footer text. ### SlideLayoutIdList Class -The **SlideLayoutIdList** class corresponds to the \ element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification introduces the \ element: +The `SlideLayoutIdList` class corresponds to the `` element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification introduces the `` element: This element specifies the existence of the slide layout identification list. This list is contained within the slide master and is used to determine which layouts are being used within the slide master file. Each layout within the list of slide layouts has its own identification number and relationship identifier that uniquely identifies it within both the presentation document and the particular master slide within which it is used. ### Timing Class -The **Timing** class corresponds to the \ element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification introduces the \ element: +The `Timing` class corresponds to the `` element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification introduces the `` element: -This element specifies the timing information for handling all animations and timed events within the corresponding slide. This information is tracked via time nodes within the \ element. More information on the specifics of these time nodes and how they are to be defined can be found within the Animation section of the PresentationML framework. +This element specifies the timing information for handling all animations and timed events within the corresponding slide. This information is tracked via time nodes within the `` element. More information on the specifics of these time nodes and how they are to be defined can be found within the Animation section of the PresentationML framework. ### Transition Class -The **Transition** class corresponds to the \ element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification introduces the \ element: +The `Transition` class corresponds to the `` element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification introduces the `` element: This element specifies the kind of slide transition that should be used to transition to the current slide from the previous slide. That is, the transition information is stored on the slide that appears after the transition is complete. ### TextStyles Class -The **TextStyles** class corresponds to the \ element. The following information from the [ISO/IEC 29500](https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=51463) specification introduces the \ element: +The `TextStyles` class corresponds to the `` element. The following information from the [!include[ISO/IEC 29500 URL](../includes/iso-iec-29500-link.md)] specification introduces the `` element: This element specifies the text styles within a slide master. Within this element is the styling information for title text, the body text and other slide text as well. This element is only for use within the Slide Master and thus sets the text styles for the corresponding presentation slides. @@ -122,9 +122,9 @@ Consider the case where we would like to specify the title text for a master sli - vv + - + @@ -138,22 +138,22 @@ In the previous example the title text is set according to the above formatting ## Working with the SlideMaster Class -As shown in the Open XML SDK code sample that follows, every instance of the **SlideMaster** class is associated with an instance of the **[SlideMasterPart](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.slidemasterpart.aspx)** class, which represents a slide master part, one of the required parts of a PresentationML presentation file package. Each **SlideMaster** class instance must also be associated with instances of the **[SlideLayout](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.slidelayout.aspx)** and <**[Slide](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.slide.aspx)** classes, which are in turn associated with similarly named required presentation parts, represented by the **[SlideLayoutPart](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.slidelayoutpart.aspx)** and **[SlidePart](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.slidepart.aspx)** classes. +As shown in the Open XML SDK code sample that follows, every instance of the `SlideMaster` class is associated with an instance of the class, which represents a slide master part, one of the required parts of a PresentationML presentation file package. Each `SlideMaster` class instance must also be associated with instances of the and classes, which are in turn associated with similarly named required presentation parts, represented by the and classes. -The **SlideMaster** class, which represents the \ element, is therefore also associated with a series of other classes that represent the child elements of the \ -element. Among these classes, as shown in the following code sample, are the **CommonSlideData** class, the **ColorMap** class, the **[ShapeTree](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.shapetree.aspx)** class, and the **[Shape](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.shape.aspx)** class. +The `SlideMaster` class, which represents the `` element, is therefore also associated with a series of other classes that represent the child elements of the `` +element. Among these classes, as shown in the following code sample, are the `CommonSlideData` class, the `ColorMap` class, the class, and the class. ## Open XML SDK Code Example -The following method from the article [How to: Create a presentation document by providing a file name](/office/open-xml/how-to-create-a-presentation-document-by-providing-a-file-name) adds a new slidemaster part to an existing presentation and creates an instance of an Open XML SDK**SlideMaster** class in the new slide master part. The **SlideMaster** class constructor creates instances of the **CommonSlideData** class and the **ColorMap**, **SlideLayoutIdList**, and **TextStyles** classes. The **CommonSlideData** class constructor creates an instance of the **[ShapeTree](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.shapetree.aspx)** class, whose constructor in turn creates additional class instances: an instance of the **[NonVisualGroupShapeProperties](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.nonvisualgroupshapeproperties.aspx)** class, an instance of the **[GroupShapeProperties](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.groupshapeproperties.aspx)** class, and an instance of the **[Shape](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.shape.aspx)** class, among others. +The following method from the article [How to: Create a presentation document by providing a file name](./how-to-create-a-presentation-document-by-providing-a-file-name.md) adds a new slidemaster part to an existing presentation and creates an instance of an Open XML SDK `SlideMaster` class in the new slide master part. The `SlideMaster` class constructor creates instances of the `CommonSlideData` class and the `ColorMap`, `SlideLayoutIdList`, and `TextStyles` classes. The `CommonSlideData` class constructor creates an instance of the class, whose constructor in turn creates additional class instances: an instance of the class, an instance of the class, and an instance of the class, among others. -The namespace represented by the letter *P* in the code is the **[DocumentFormat.OpenXml.Presentation](https://msdn.microsoft.com/library/office/documentformat.openxml.presentation.aspx)** namespace. +The namespace represented by the letter *P* in the code is the namespace. ### [C#](#tab/cs) -[!code-csharp[](../../samples/presentation/working_with_slide_masters/cs/Program.cs)] +[!code-csharp[](../../samples/presentation/create_by_providing_a_file_name/cs/Program.cs#snippet99)] ### [Visual Basic](#tab/vb) -[!code-vb[](../../samples/presentation/working_with_slide_masters/vb/Program.vb)] +[!code-vb[](../../samples/presentation/create_by_providing_a_file_name/vb/Program.vb#snippet99)] ## Generated PresentationML @@ -161,7 +161,7 @@ When the Open XML SDK code is run, the following XML is written to the Presentat ```xml - + @@ -171,7 +171,7 @@ When the Open XML SDK code is run, the following XML is written to the Presentat - + @@ -179,7 +179,7 @@ When the Open XML SDK code is run, the following XML is written to the Presentat name="Title Placeholder 1" /> + xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" /> @@ -187,9 +187,9 @@ When the Open XML SDK code is run, the following XML is written to the Presentat - - - + + + @@ -209,7 +209,7 @@ When the Open XML SDK code is run, the following XML is written to the Presentat + xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" /> @@ -222,6 +222,9 @@ When the Open XML SDK code is run, the following XML is written to the Presentat ## See also [About the Open XML SDK for Office](../about-the-open-xml-sdk.md) + [How to: Create a Presentation by Providing a File Name](how-to-create-a-presentation-document-by-providing-a-file-name.md) + [How to: Insert a new slide into a presentation](how-to-insert-a-new-slide-into-a-presentation.md) + [How to: Delete a slide from a presentation](how-to-delete-a-slide-from-a-presentation.md) diff --git a/docs/spreadsheet/how-to-add-custom-ui-to-a-spreadsheet-document.md b/docs/spreadsheet/how-to-add-custom-ui-to-a-spreadsheet-document.md index e6f6af76..6a0b9776 100644 --- a/docs/spreadsheet/how-to-add-custom-ui-to-a-spreadsheet-document.md +++ b/docs/spreadsheet/how-to-add-custom-ui-to-a-spreadsheet-document.md @@ -11,35 +11,27 @@ ms.suite: office ms.author: o365devx author: o365devx ms.topic: conceptual -ms.date: 11/01/2017 +ms.date: 01/09/2025 ms.localizationpriority: high --- # Add custom UI to a spreadsheet document -This topic shows how to use the classes in the Open XML SDK for Office to programmatically add custom UI, modifying the ribbon, to an Microsoft Excel 2010 or Microsoft Excel 2013 worksheet. It contains an example **AddCustomUI** method to illustrate +This topic shows how to use the classes in the Open XML SDK for Office to programmatically add custom UI, modifying the ribbon, to a Microsoft Excel worksheet. It contains an example `AddCustomUI` method to illustrate this task. ## Creating Custom UI -Before using the Open XML SDK to create a ribbon customization in an Excel workbook, you must first create the customization content. Describing the XML required to create a ribbon customization is beyond the scope of this topic. In addition, you will find it far easier to use the Ribbon Designer in Visual Studio 2010 to create the customization for you. For more information about customizing the ribbon by using the Visual Studio Ribbon Designer, see [Ribbon Designer](https://msdn.microsoft.com/library/26617206-f4da-416f-a18a-d817b2d4872d(Office.15).aspx) and [Walkthrough: Creating a Custom Tab by Using the Ribbon Designer](https://msdn.microsoft.com/library/312865e6-950f-46ab-88de-fe7eb8036bfe(Office.15).aspx). -For the purposes of this demonstration, you will need an XML file that contains a customization, and the following code provides a simple customization (or you can create your own by using the Visual Studio Ribbon Designer, and then right-click to export the customization to an XML file). Copy the following content into a text file that is named AddCustomUI.xml for use as part of this example. This XML content describes a ribbon customization that includes a button labeled "Click Me!" in a group named Group1 on the **Add-Ins** tab in Excel. When you click the button, it attempts to run a macro named **SampleMacro** in the host workbook. - -```xml - - - - - -