DevExpress Presentation API Library: Configure Slide Masters and Layouts
- 11 minutes to read
Important
The DevExpress Presentation API Library is currently available as a Community Technology Preview (CTP). Note that we do not recommend that you integrate pre-release libraries into mission-critical software applications. You can try the library and share your feedback so that we can make necessary adjustments before the official release. To start a conversation, submit a ticket via the DevExpress Support Center — we’d love to hear from you.
The Slide Master is a top-level template slide that you can use as a base for other slides. This master slide shares content, layouts, and text styles with all derived slides. Changes made to the slide master are applied to all descendant slides. If a presentation has multiple slide masters, you can apply different slide masters to different slides within the same presentation.
A slide master stores predefined layouts that you use to organize content on a slide. A layout arranges content placeholders. Each valid presentation file contains at least one slide master with one associated layout element.
Add Slide Masters
Use the Presentation.SlideMasters property to access a collection of slide masters within the presentation. Each individual slide master is a SlideMaster object. For each master, you can specify the following options:
- Layouts
- Stores the layout presets associated with the slide master. When you create a new slide master, the Presentation API library populates it with a predefined set of layouts. For more information, see the following section: Layout Presets.
- Shapes
- Stores shapes associated with the slide master. Shapes added to this collection are displayed on all descendant slides unless you disable a slide’s ShowMasterShapes property.
- Background
- Specifies the background for descendant slides.
- Name
- Specifies the slide master name. The name is optional and does not have to be unique.
The following code snippet adds two slide masters to a presentation. Since each presentation must have a slide master, a newly created presentation initially contains a default slide master. You can call ResetTo to replace the default slide master with the newly created slide master.
using DevExpress.Docs.Presentation;
Presentation presentation = new Presentation();
SlideMaster slideMaster1 = new SlideMaster("master");
//...
presentation.SlideMasters.ResetTo(slideMaster1);
SlideMaster slideMaster2 = new SlideMaster();
// ...
presentation.SlideMasters.Add(slideMaster2);
You can also access the SlideMasters collection and call Remove and RemoveAt methods to delete a SlideMaster instance from the collection. Note that if you try to save a presentation with an empty SlideMasters collection, the library throws an InvalidOperationException.
Layout Presets
A manually created slide master and the default slide master in a new presentation contain the following set of predefined layouts. Each layout delivers an individual set of placeholders available in a layout’s Shapes collection:
- Title
Placeholders:
CenteredTitle,Subtitle,DateAndTime,Footer,SlideNumber
- Object
Placeholders:
Title,Object,DateAndTime,Footer,SlideNumber
- SectionHeader
Placeholders:
Title,Body,DateAndTime,Footer,SlideNumber
- TwoObjects
Placeholders:
Title,Object,Object,DateAndTime,Footer,SlideNumber
- TwoTextsAndTwoObjects
Placeholders:
Title,Body,Object,Body,Object,DateAndTime,Footer,SlideNumber
- TitleOnly
Placeholders:
Title,DateAndTime,Footer,SlideNumber
- Blank
Placeholders:
DateAndTime,Footer,SlideNumber
- TitleObjectAndCaption
Placeholders:
Title,Object,Body,DateAndTime,Footer,SlideNumber
- PictureAndCaption
Placeholders:
Title,Picture,Body,DateAndTime,Footer,SlideNumber
- VerticalText
Placeholders:
Title,Body,DateAndTime,Footer,SlideNumber
- VerticalTitleAndText
Placeholders:
Title,Body,DateAndTime,Footer,SlideNumber
The SlideLayoutType enumeration lists all layout presets available for PPTX format.
Add a Layout
In addition to default layouts, you can create and add your own layouts.
To configure a slide layout, create a SlideLayout instance and pass the layout type in the constructor. Since each layout should be linked to a single slide master, the Presentation API library automatically adds the layout to the first slide master in the SlideMasters collection once you assign the layout to a slide. If you want the layout to link to the specified slide master, add this layout instance to the slide master’s SlideMaster.Layouts collection.
For each individual layout, you can specify the following options:
- Shapes
- Stores shapes associated with the layout. Shapes added to this collection are displayed on all descendant slides unless you disable a slide’s ShowMasterShapes property.
- LayoutType
- Returns the layout type. The SlideLayoutType enumeration lists all layout types.
- Background
- Specifies the background for descendant slides.
- Name
- Specifies the layout name. The name is optional and does not have to be unique.
using DevExpress.Docs.Presentation;
SlideMaster slideMaster = new SlideMaster("master");
SlideLayout layout1 = new SlideLayout(SlideLayoutType.Title);
layout1.Background = new CustomSlideBackground(new SolidFill(Color.LightBlue));
slideMaster.Layouts.ResetTo(layout1); // ResetTo replaces default layouts with the newly created layout.
// ...
// Call the slideMaster's Add method to add other layout instances.
// ...
The SlideLayout constructor only adds placeholder shapes for default layout types. You can obtain these placeholder shapes in the slide’s Shapes collection. For more information, refer to the following section: Access Placeholder Shapes.
For instructions on how to configure a placeholder, refer to the following section: Add Placeholders to a Layout.
Create a Slide using a Slide Master
Call the slide master’s Layouts.Get method to obtain a layout of the specified type. You can also call the Layouts.GetOrCreate method to create a layout of the requested type if it does not exist.
Slide slide = new Slide(presentation.SlideMasters[0].Layouts.GetOrCreate(SlideLayoutType.Title));
Set Slide Background
A background set at the Slide Master or the layout level is applied to all descendent slides. A background is applied from the slide master down to an individual layout, and then to a slide. You can set a background individually for each slide. In this case, the slide background redefines both the layout and master backgrounds for that slide.
slideMaster.Background = new CustomSlideBackground(new SolidFill(Color.LightPink));
layout1.Background = new CustomSlideBackground(new SolidFill(Color.LightBlue));
For more information on how to format slide backgrounds, refer to the following help topic: DevExpress Presentation API Library: Set Slide Background.
Add Shapes
Shapes added to the slide master or layout are displayed on all descendant slides unless you disable the slide’s ShowMasterShapes property.
In the following code snippet, a slide obtains shapes both from a slide master and a layout:
Presentation presentation = new Presentation();
presentation.Slides.Clear();
SlideMaster slideMaster1 = new SlideMaster("master");
presentation.SlideMasters.ResetTo(slideMaster1);
Shape shape1 = new Shape(ShapeType.Heart) { Width = 500, Height = 500, X = 100, Y = 100, Fill = new SolidFill(Color.Red) };
slideMaster1.Shapes.Add(shape1);
SlideLayout layout1 = new SlideLayout();
slideMaster1.Layouts.Add(layout1);
Shape shape2 = new Shape(ShapeType.Diamond) { Width = 500, Height = 500, X = 2500, Y = 1500, Fill = new SolidFill(Color.Blue) };
layout1.Shapes.Add(shape2);
Slide slide = new Slide(layout1);
presentation.Slides.Add(slide);
You can also add shapes directly to a slide. For more information, refer to the following help topic: Add a Shape
Access Placeholder Shapes
If you create a slide based on a layout, the slide inherits placeholder shapes from this layout (except for DateAndTime, Footer, SlideNumber). You can access them in a slide’s Shapes collection.
Use a shape’s PlaceholderSettings property to access shape placeholder options:
- Type
- Specifies the placeholder type. The PlaceholderType enumeration contains all available types.
- Index
- Specifies the placeholder zero-based index.
- Orientation
- Specifies the placeholder orientation.
- Size
- Specifies the placeholder size.
The following code snippet adds text to a title placeholder:
Slide slide = new Slide(new SlideLayout(SlideLayoutType.Title));
foreach (Shape shape in slide.Shapes) {
if (shape.PlaceholderSettings.Type is PlaceholderType.CenteredTitle) {
TextArea textArea = new TextArea();
TextParagraph paragraph = new TextParagraph();
paragraph.Runs.Add(new TextRun { Text = "Presentation Title", CharacterProperties = new TextCharacterProperties { Fill = new SolidFill(Color.RoyalBlue) } });
textArea.Paragraphs.Add(paragraph);
shape.TextArea = textArea;
}
}
presentation.Slides.Add(slide);
You can access DateAndTime, Footer, and SlideNumber placeholders at the slide level:
- ActualSlideNumberPlaceholder
- Returns the first found slide number placeholder in the Shapes collection.
- ActualFooterPlaceholder
- Returns the first found footer placeholder in the Shapes collection.
- ActualDateTimePlaceholder
- Returns the first found date and time placeholder in the Shapes collection.
The following code snippet changes date format for a date and time slide placeholder shape:
presentation.HeaderFooterManager.AddDateTimePlaceholder(slide);
TextField date = slide.ActualDateTimePlaceholder.TextArea.Paragraphs[0].Runs[0] as TextField;
slide.ActualDateTimePlaceholder.PlaceholderSettings.Size = PlaceholderSize.Full;
date.FieldType = TextFieldType.DateTime2;
date.CharacterProperties = new TextCharacterProperties() { FontSize = 22 };
Add Placeholders to a Layout
If you create a custom layout, you may need to arrange your own set of placeholders on it. To create a placeholder shape, initialize a Shape instance and add it to the layout’s Shapes collection. Specify the shape PlaceholderSettings, such as Type, Index, and Size.
The following code snippet creates a placeholder shape, adds it to a custom layout, and populates this placeholder with content in a slide:
using DevExpress.Docs.Presentation;
using System.Drawing;
namespace PptxExportSample;
public class Program {
public static void Main(string[] _) {
// Create a new presentation and clear default slides
Presentation presentation = new Presentation();
presentation.Slides.Clear();
// Create a custom slide layout and add it to the first slide master (default)
SlideLayout layout = new SlideLayout(SlideLayoutType.Custom, "customlayout");
presentation.SlideMasters[0].Layouts.Add(layout);
// Create a rectangle shape to use it as a placeholder
Shape placeholder = new Shape(ShapeType.Rectangle);
placeholder.Name = "placeholder";
placeholder.Outline = new OutlineStyle { Fill = new SolidFill(Color.DarkRed), Width = 10 };
placeholder.Fill = new SolidFill(Color.White);
// Configure placeholder settings
PlaceholderSettings placeholderSettings = new PlaceholderSettings();
placeholderSettings.Size = PlaceholderSize.Full;
placeholderSettings.Type = PlaceholderType.Object;
placeholderSettings.Index = 0;
placeholder.PlaceholderSettings = placeholderSettings;
// Add the placeholder shape to the custom layout
layout.Shapes.Add(placeholder);
// Create a slide based on the custom layout and add it to the presentation
Slide slide1 = new Slide(layout);
presentation.Slides.Add(slide1);
// Set text and formatting for the placeholder shape in the slide
foreach (Shape s in slide1.Shapes) {
if (s.PlaceholderSettings.Index == 0) {
s.TextArea.Text = "Text";
s.TextArea.Level1ParagraphProperties.TextProperties.Fill = new SolidFill(Color.Black);
s.TextArea.Properties.AnchorCenter = true;
s.TextArea.Level1ParagraphProperties.ListBullet = ListBullet.None;
}
}
}
}