Slide layout authoring¶
Create slides from a theme’s layouts, and fill in their text and image placeholders.
Each placeholder has a name that identifies it within a slide layout. A text placeholder takes text, an image placeholder takes an image, and a movie or audio placeholder has no setter.
summarize_slide_layouts¶
- creator_studio_doc_format.authoring.summarize_slide_layouts(theme)[source]¶
Returns the placeholders of each slide layout.
- Parameters:
The theme that holds the slide layouts.
- Returns:
Each layout’s placeholders, keyed by layout name, or
{}whentheme.slide_layoutsis absent.- Return type:
dict[str, list[LayoutPlaceholderSummary]]
LayoutPlaceholderSummary¶
- class creator_studio_doc_format.authoring.LayoutPlaceholderSummary(name, object_case, prompt, tag)[source]¶
A read-only summary of a placeholder in a slide layout.
One summary stands for every placeholder that shares its name and setter. You don’t create a summary directly.
summarize_slide_layouts()returns them.- name : str¶
The placeholder’s name within its layout, which a setter takes. A custom placeholder’s name is its tag. Any other placeholder’s name is its kind’s member name, such as
"TITLE".
- object_case : str¶
The case the placeholder’s canvas object holds. A text placeholder holds a case such as
"shape"or"textbox", and an image placeholder holds"image".
- prompt : str | None¶
The prompt or sample text Keynote shows in the placeholder. It’s
Nonewhen there’s none, as for an image, movie, or audio placeholder.
- tag : str | None¶
The label the theme’s designer gives a custom placeholder. It’s
Nonefor a predefined one such as"TITLE".
slide_from_layout¶
- creator_studio_doc_format.authoring.slide_from_layout(theme, layout_name)[source]¶
Returns a new slide made from a layout, as Keynote creates one.
- Parameters:
The theme to instantiate the layout from.
The layout’s name, which is a key of the result of
summarize_slide_layouts().
- Returns:
The new slide. Only its
"TITLE"and"BODY"placeholders start empty. A custom placeholder keeps its sample text, and an image placeholder keeps its sample photo until a setter replaces it. Add the slide topresentation.slidesto put it in a document.- Return type:
- Raises:
KeyError–layout_namematches no layout identifier or layout name intheme.
set_slide_placeholder_text¶
-
creator_studio_doc_format.authoring.set_slide_placeholder_text(slide, placeholder_name, lines, *, list_levels=
None)[source]¶ Writes lines into a text placeholder and returns the paragraphs it wrote.
Every line takes the placeholder’s own paragraph and text style at every level. Some built-in themes style each level of the sample text differently, so a nested line needs that level’s style. Set it on the returned paragraph.
- Parameters:
The slide to write into.
The text placeholder’s name, as
summarize_slide_layouts()reports it.One paragraph’s text, or a list with one text per paragraph.
Noneor[]clears the placeholder, and""writes an empty run.Each line’s list level, from 0 for the top level through 8, with one entry per line. A placeholder with text that is a plain string ignores it.
- Returns:
The paragraphs written into the placeholder. They’re live, so changing one changes the slide. A placeholder with text that is a plain string has no paragraphs, so the result is
[]and the function joins the lines with newlines.- Return type:
list[Paragraph]- Raises:
KeyError– No placeholder namedplaceholder_nameexists onslide.TypeError–placeholder_namenames an image, movie, or audio placeholder, or a text placeholder that has noText.ValueError–list_levelshas a different length thanlines, or a level outside 0 through 8.
set_slide_placeholder_image¶
-
creator_studio_doc_format.authoring.set_slide_placeholder_image(slide, placeholder_name, resource, *, size=
None)[source]¶ Points an image placeholder at a resource and returns the image.
Important
The function doesn’t store the image’s bytes. An indirect
resourceneeds them indoc.resources, and by default the document’ssaveraisesValueErrorwithout them.- Parameters:
The slide to write into.
The image placeholder’s name, as
summarize_slide_layouts()reports it.The image’s resource.
The width and height of the image
resourceholds. The function then fills the placeholder’s mask with the image and centers it there, as with Replace Image in Keynote. Only the aspect ratio matters.Nonekeeps the placeholder’s geometry, and the image stretches to it.
- Returns:
The placeholder’s image, now pointing at
resource. It is live, so changing itsgeometryadjusts the crop.- Return type:
- Raises:
KeyError– No placeholder namedplaceholder_nameexists onslide.TypeError–placeholder_namenames a text, movie, or audio placeholder.ValueError–sizehas a width or height that isn’t positive.
See also