Edit PowerPoint Presentations
This example demonstrates standard open-edit-save cycle with Presentation documents, using different options on every step.
Presentation documents are presented by many formats: PPT, PPTX, PPTM, PPS(X/M), POT(X/M) and other, which are supported by GroupDocs.Editor as a separate format family among all others. Same like for all other family formats, Presentation family has its own load, edit and save options. Presentation format has significant distinction from the WordProcessing and all textual formats, and at the same time big similarity with Spreadsheet formats, — it has no pages, but instead of pages it has slides (like Spreadsheet has tabs). Like tabs in Spreadsheets, slides in Presentations are completely separate one from each other and has no valid representation in HTML markup, so the only way to edit slides is to edit them separately, one slide per one editing procedure.
As a result, a Presentation document with multiple slides is loaded into the Editor class. Then, in order to open document for editing by calling an Editor.Edit method, user should select desired slide for editing by specifying its index in the PresentationEditOptions. As a result, user will obtain an instance of EditableDocument class, that holds that edited slide. For editing another slide, user should perform another call of the Editor.edit() method with another slide index, and obtain a new instance of EditableDocument class. Finally, when saving edited slides back to Presentation format, user should save every EditableDocument instance separately.
Like all Office OOXML formats, Presentation documents can be encrypted with password. GroupDocs.Editor supports opening password-protected Presentation documents (password should be specified in the PresentationLoadOptions) and creating password-protected documents (password should be specified in the PresentationSaveOptions).
First step for edit a document is to load it. In order to load presentation to the Editor class, user should use the PresentationLoadOptions class. It is not necessary in some general cases — even without PresentationLoadOptions the GroupDocs.Editor is able to recognize presentation format and apply appropriate default load options automatically. But when presentation is encoded, the PresentationLoadOptions is the only way to set a password and load the document properly.
If document is encoded, but password is not set in the PresentationLoadOptions, or PresentationLoadOptions is not specified at all, then PasswordRequiredException exception will be thrown. If password is set, but is incorrect, then IncorrectPasswordException will be thrown. If password is set, but the document is not encoded, then password will be ignored.
Below is an example of loading a presentation document from file path with load options and password.
String inputPptxPath = "C://input//presentation.pptx";
PresentationLoadOptions loadOptions = new PresentationLoadOptions();
loadOptions.setPassword("password");
Editor editor = new Editor(inputPptxPath, loadOptions);
For opening Presentation document for edit a PresentationEditOptions class should be used. It has two properties: getSlideNumber() of Integer type, and a getShowHiddenSlides(), that is a boolean flag.
getSlideNumber() is a zero-based index of a slide, that allows to specify and select one particular slide from a presentation to edit. If lesser then 0, the first slide will be selected (same as SlideNumber = 0). If greater then amount of all slides in presentation, the last slide will be selected. If input presentation contains only single slide, this option will be ignored, and this single slide will be edited. By default is 0, that implies first slide for edit.
getShowHiddenSlides() is a boolean flag, which specifies whether the hidden slides should be included or not. Default is false — hidden slides are not shown and exception will be thrown while trying to edit them. So, if input Presentation has 3 slides, where 2nd is hidden, user has specified SlideNumber = 1 (2nd slide) and simultaneously ShowHiddenSlides = false, the InvalidOperationException will be thrown.
If parameterless overload of the Editor.edit() method is used, the default PresentationEditOptions instance will be used: first slide and disabled getShowHiddenSlides().
Code example below demonstrates all options, described above. Let’s assume, that Presentation document with at least 3 slides is already loaded into the Editor class.
//parameterless overload is used => default PresentationEditOptions is applied, which means 1st slide
EditableDocument firstSlide = editor.edit();
PresentationEditOptions editOptions2 = new PresentationEditOptions();
editOptions2.setSlideNumber(1); //index is 0-based, so this is 2nd slide
EditableDocument secondSlide = editor.edit(editOptions2);
PresentationEditOptions editOptions3 = new PresentationEditOptions();
editOptions3.setSlideNumber(2); //index is 0-based, so this is 3rd slide
editOptions3.setShowHiddenSlides(true); //if 3rd slide is hidden, it will be opened anyway
EditableDocument thirdSlide = editor.edit(editOptions3);
PresentationSaveOptions class is designed for saving the edited Presentation documents. This class has one constructor, which has one parameter — a Presentation format, in which the output document should be saved. This output format is represented by the PresentationFormats struct. After creating an instance, output format can be obtained or modified later, through the getOutputFormat() property. This is the only parameter, which is necessary for saving the document: all others are optional and may be omitted.
Along with format, user is able to specify a password through the getPassword() string property — in this case output document will be encoded and protected with this password. By default password is not set, which implies that output document will be unprotected. This is shown in example below, where it is supposed that a user has an EditableDocument instance with edited slide.
PresentationSaveOptions saveOptions = new PresentationSaveOptions(PresentationFormats.Pptm);
saveOptions.setPassword("new password");
EditableDocument afterEdit = /* obtain it from somewhere */;
FileStream outputStream = /* obtain it from somewhere */;
//saving edited slide to specified stream in PPTM format and with password encoding
editor.save(afterEdit, outputStream, saveOptions);
