Shapes¶
Draw paths with a fill and a stroke, and connect objects with lines.
Shape¶
-
class creator_studio_doc_format.core.Shape(*, preset_identifier=
'', identifier=None, geometry=None, aspect_ratio_locked=False, description=None, title=None, title_is_positioned_on_top=True, caption=None, path=None, tail=LineEnd.NONE, head=LineEnd.NONE, fill=None, stroke=Stroke(line=Line()), opacity=1, shadow=Override.not_set(), reflection=None, layout_properties=None, paragraph_properties=None, text=None, **extra_data)[source]¶ A path with a fill and a stroke.
When
geometryis absent, the geometry defaults to the smallest rectangle that encloses the path. Shapes can have an open or a closed path; a path is _open_ when it has a single subpath, noclosepathcommand, and ends that don’t meet. Open shapes can have endpoints,headandtail. Keynote reads apaththat is a single, straight, open segment as a line and takes its styling from the line presets. A shape with eitherGeometry.width_validorGeometry.height_validset tofalsebecomes an auto-sizing text box. Paths that aren’t straight lines can contain text that appears inside the shape.-
field identifier : str | None =
None¶ An identifier for this object that other objects use to refer to it. This identifier must be unique across the whole document.
-
field geometry : Geometry | None =
None¶ The object’s position and size. If this value is absent, Keynote places the object automatically, with a default position and size for its kind.
-
field aspect_ratio_locked : bool =
False¶ A Boolean value that indicates whether the object’s width-to-height ratio is locked when the object resizes. The lock doesn’t constrain the
geometryproperty. If this property is absent, images, movies, and groups default totrue, and other objects tofalse.
-
field description : str | None =
None¶ The accessibility description for the object, read aloud by assistive technologies such as VoiceOver.
-
field title_is_positioned_on_top : bool =
True¶ When
true, the title appears above the object; whenfalse, the title appears below the object, above the caption if there is one. Defaults totrue. Keynote ignores this when the object has none, or when it’s hidden withLabel.is_visibleset tofalse; Keynote places a hidden title above the object, where it appears when it shows again.
-
field caption : Label | None =
None¶ The object’s caption, which Keynote always places below the object. If a caption is off, you still write it out with
Label.is_visibleset tofalse, so having a value doesn’t mean the caption shows.
-
field path : Path | None =
None¶ The path that forms the shape’s outline. Either this value or
geometrymust be present. If absent, Keynote assume this shape to be a rectangle the same size asgeometry.
-
field tail : LineEnd =
LineEnd.NONE¶ The tail end of the shape, which is a line-end decoration, such as an arrowhead, at the first point of the shape’s
path. Keynote only display it for an open path. The default isnone.
-
field head : LineEnd =
LineEnd.NONE¶ The head end of the shape, which is a line-end decoration, such as an arrowhead, at the last point of the shape’s
path. Keynote only displays it for an open path. The default isnone.
-
field fill : Fill | None =
None¶ The fill of the shape’s interior. If absent, it uses the the fill from the shape’s preset style.
-
field opacity : float =
1¶ The shape’s opacity, in the range
0to1.
-
field reflection : Reflection | None =
None¶ The reflection for the shape.
-
field layout_properties : LayoutProperties | None =
None¶ Layout overrides, such as insets and columns, for the shape’s text.
-
field paragraph_properties : ParagraphProperties | None =
None¶ Paragraph-level style, such as alignment and spacing, for the shape’s text.
-
field identifier : str | None =
Rect¶
-
class creator_studio_doc_format.core.Rect(*, preset_identifier=
'', position, size, **extra_data)[source]¶ An axis-aligned rectangle in whichever coordinate space the property using it defines.
Path¶
-
class creator_studio_doc_format.core.Path(*, preset_identifier=
'', bezier=None, **extra_data)[source]¶ A path that traces the outline of a shape or of an image’s mask.
Only one form is defined so far; later versions of the format can add others without changing how a shape or an image mask refers to its outline.
-
field bezier : BezierPath | None =
None¶ A path described by an SVG path string. This is the only supported path representation.
-
field bezier : BezierPath | None =
BezierPath¶
-
class creator_studio_doc_format.core.BezierPath(*, preset_identifier=
'', path, space=None, **extra_data)[source]¶ A path as an SVG path string, together with the coordinate space in which its points are expressed.
- field path : str [Required]¶
The path as SVG path data: the value of the
dattribute of a<path>element; it must be non-empty and must begin with a moveto command. Any standard path command is accepted when reading, but only absolute moveto, lineto, curveto, and closepath commands are produced when writing, so the exact command sequence isn’t guaranteed to be preserved.
-
field space : Rect | None =
None¶ If present,
pathis treated as relative to this rectangle, and then stretched proportionally to cover the bounding box of the owner’s geometry (Image.Mask.geometryfor an image mask) before the owner’s flip and rotation apply. The owner’s size and position then become the bounds of the mapped path, so whenspacediffers from the path’s tight bounds, the owner’s written size and position aren’t preserved, unless the owner sizes itself to fit its text. When absent, the path’s tight bounds are used. When the owner has no geometry,spacemust equal those bounds, and the points are then absolute coordinates in the containing slide.
Stroke¶
-
class creator_studio_doc_format.core.Stroke(*, preset_identifier=
'', empty=None, frame=None, line=None, **extra_data)[source]¶ A stroke drawn along a path, such as a border around an object.
The stroke is a line or a picture frame, or
emptyfor no stroke or border.-
field empty : Literal[True] | None =
None¶ No stroke or border.
-
field empty : Literal[True] | None =
Line¶
-
class creator_studio_doc_format.core.Line(*, preset_identifier=
'', color=None, width=1, pattern=Pattern.SOLID, **extra_data)[source]¶ A stroke or border that the reader draws as a line in one of several styles.
-
field width : float =
1¶ The width of the stroke, in points.
- Constraints:
ge = 0.25
le = 100
-
field width : float =
Pattern¶
- class creator_studio_doc_format.core.Pattern(str, Enum)[source]¶
The pattern that the reader uses to draw a stroke: solid, one of the dash styles, or one of the brush styles.
round_dashalso rounds the line’s caps and joins, and a dashed line with round caps is written asround_dashregardless of its dash pattern. Without round caps, a dash pattern that doesn’t match one of these cases is written asshort_dash.A field accepts a member or its value, so
Pattern.CALLIGRAPHYand'calligraphy'are the same. The member’s name as a string isn’t accepted.-
CALLIGRAPHY =
'calligraphy'¶ A line that appears to be drawn with a calligraphy pen. Shown in Keynote as Calligraphy.
-
CHALK =
'chalk'¶ A line that appears to be drawn with a piece of chalk pulled along a chalkboard. Shown in Keynote as Chalk.
-
DRY_BRUSH =
'dry_brush'¶ A line that appears to be painted with a dry brush on paper. Shown in Keynote as “Dry brush.”
-
FEATHERED_BRUSH =
'feathered_brush'¶ A line that appears to be painted with a feathered brush on paper. Shown in Keynote as “Feathered brush.”
-
LONG_DASH =
'long_dash'¶ A dashed line with long dashes. Shown in Keynote as “Long dash.”
-
MEDIUM_DASH =
'medium_dash'¶ A dashed line with medium dashes. Shown in Keynote as “Medium dash.”
-
PEN =
'pen'¶ A line that appears to be drawn with a pen that has uneven ink flow. Shown in Keynote as Pen.
-
ROUND_DASH =
'round_dash'¶ A dotted line, drawn with small round dashes. Shown in Keynote as “Rounded dash.”
-
SHORT_DASH =
'short_dash'¶ A dashed line with short dashes. Shown in Keynote as “Short dash.”
-
SOLID =
'solid'¶ A solid line. Shown in Keynote as Solid.
-
CALLIGRAPHY =
Frame¶
-
class creator_studio_doc_format.core.Frame(*, preset_identifier=
'', name, scale_percent=100, **extra_data)[source]¶ A picture frame drawn around an object as its border.
-
field scale_percent : float =
100¶ The scale applied to the picture frame artwork, as a percentage, in the range
10to100. Some picture frames have an effective minimum higher than 10%, and a smaller value is raised to that minimum.- Constraints:
ge = 10
le = 100
-
field scale_percent : float =
Name¶
- class creator_studio_doc_format.core.Name(str, Enum)[source]¶
The name of the picture frame that Keynote uses to draw the border.
This frame is one of the artworks that Keynote ships. Only the frame listed here can be written, so when an object has any other frame, Keynote writes it with no border. If a frame of the given name can’t be found, the stroke is skipped rather than being replaced with a line, leaving the object unframed.
A field accepts a member or its value, so
Name.ANTIQUEand'antique'are the same. The member’s name as a string isn’t accepted.-
ANTIQUE =
'antique'¶
-
CRAYON_LINE =
'crayon_line'¶
-
FORMAL_INSET =
'formal_inset'¶
-
FORMAL_SHADOW =
'formal_shadow'¶
-
GRAPH_PAPER =
'graph_paper'¶
-
HEADLINES =
'headlines'¶
-
JET_SET =
'jet_set'¶
-
PHOTO_PORTFOLIO1 =
'photo_portfolio1'¶ The picture frame shown in Keynote as “Photo portfolio.”
-
PORTFOLIO_INSET =
'portfolio_inset'¶
-
PUSHPIN =
'pushpin'¶
-
RENAISSANCE1 =
'renaissance1'¶ The picture frame shown in Keynote as Renaissance.
-
SCRAPBOOK2B =
'scrapbook2b'¶ The picture frame shown in Keynote as Scrapbook 2.
-
STORYBOARD =
'storyboard'¶
-
VINTAGE_INSET =
'vintage_inset'¶
-
ANTIQUE =
ConnectionLine¶
-
class creator_studio_doc_format.core.ConnectionLine(*, preset_identifier=
'', identifier=None, geometry=None, aspect_ratio_locked=False, description=None, line_type=LineType(straight=True), tail, head, stroke=Stroke(line=Line()), opacity=1, shadow=Override.not_set(), reflection=None, **extra_data)[source]¶ A line drawn from its tail end to its head end, each of which can attach to another object.
The route comes from
tail,head, and (for a curved or corner line) the control position carried byline_type. Because the line’s position and size follow from the route,geometryonly transforms the supplied end points and control position, and is omitted when Keynote writes out a connection line.-
field identifier : str | None =
None¶ An identifier for this object that other objects use to refer to it. This identifier must be unique across the whole document.
-
field geometry : Geometry | None =
None¶ The object’s position and size. If this value is absent, Keynote places the object automatically, with a default position and size for its kind.
-
field aspect_ratio_locked : bool =
False¶ A Boolean value that indicates whether the object’s width-to-height ratio is locked when the object resizes. The lock doesn’t constrain the
geometryproperty. If this property is absent, images, movies, and groups default totrue, and other objects tofalse.
-
field description : str | None =
None¶ The accessibility description for the object, read aloud by assistive technologies such as VoiceOver.
-
field opacity : float =
1¶ The opacity of the connection line, in the range
0to1.
-
field reflection : Reflection | None =
None¶ The reflection shown for the connection line.
-
field identifier : str | None =
LineType¶
-
class creator_studio_doc_format.core.LineType(*, preset_identifier=
'', corner=None, curved=None, straight=None, **extra_data)[source]¶ How a connection line is routed between its ends.
A curved route whose control position lies almost on the line between the two ends is written back as
straight, and that position is discarded.-
field corner : Position | None =
None¶ A route that makes right-angle turns and passes through this position, though not necessarily with a corner there.
The reader usually passes straight through a position partway between the ends.
-
field curved : Position | None =
None¶ A route that bows between the ends and passes through this position.
-
field straight : Literal[True] | None =
None¶ A route that makes a straight line between its ends.
-
field corner : Position | None =
End¶
-
class creator_studio_doc_format.core.End(*, preset_identifier=
'', end_point=None, line_end=LineEnd.NONE, outset=0, anchor=None, **extra_data)[source]¶ One end of a connection line.
end_pointis effectively required: if a line’stailorheadleaves it out, the line is dropped, even if that end supplies ananchor.-
field end_point : Position | None =
None¶ Where this end of the line stops, unless
anchorattaches it to an object. Although it’s marked optional, omitting it drops the whole line, even whenanchoris present. For an attached end, give the object’s center, so a curved line bows where itsline_typeputs it.
-
field line_end : LineEnd =
LineEnd.NONE¶ The decoration shown at this end of the connection line, such as an arrowhead. The default is
none.
-
field outset : float =
0¶ When anchored, the size of the gap between the edge of the connected object and the start of the connection line, measured along the path in points. Defaults to 0, so the line begins at the edge of the connected object.
-
field end_point : Position | None =
Anchor¶
-
class creator_studio_doc_format.core.Anchor(*, preset_identifier=
'', object_id, magnet=Magnet(center=True), **extra_data)[source]¶ How one end of a connection line connects to another object.
The line stays connected as the other object moves. Anchors are resolved after the enclosing list of objects is read, so the target may appear after the line.
- field object_id : str [Required]¶
The identifier of the object this end is connected to. The reference is resolved only among the connection line’s siblings, not across the document, so the object must be a sibling of the connection line. It also can’t be a connection line, a group, an audio clip, or a shape with a straight line path. If it can’t be connected, this end is left unconnected at
ConnectionLine.End.end_pointand a warning is reported. An end connected to the object that fills thetitle,body, orslide_numberplaceholder, or a layout’sobjectplaceholder, is also left unconnected, but no warning is reported.
Magnet¶
-
class creator_studio_doc_format.core.Magnet(*, preset_identifier=
'', center=None, east=None, edge=None, floating=None, north=None, south=None, west=None, **extra_data)[source]¶ The point on the anchored object that the line connects to.
Keynote connects every line the same way, whatever this value is: aimed at the object’s center and stopped at its outline.
-
field center : Literal[True] | None =
None¶ The object’s center. It’s the only value Keynote writes.
-
field east : Literal[True] | None =
None¶ Not used.
-
field edge : Position | None =
None¶ Not used. It stands for the line meeting the object’s outline, at the position given here.
-
field floating : Position | None =
None¶ Not used. It stands for the line meeting a point not tied to the object’s outline, at the position given here.
-
field north : Literal[True] | None =
None¶ Not used.
-
field south : Literal[True] | None =
None¶ Not used.
-
field west : Literal[True] | None =
None¶ Not used.
-
field center : Literal[True] | None =
See also