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 geometry is 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, no closepath command, and ends that don’t meet. Open shapes can have endpoints, head and tail. Keynote reads a path that is a single, straight, open segment as a line and takes its styling from the line presets. A shape with either Geometry.width_valid or Geometry.height_valid set to false becomes 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 geometry property. If this property is absent, images, movies, and groups default to true, and other objects to false.

field description : str | None = None

The accessibility description for the object, read aloud by assistive technologies such as VoiceOver.

field title : Label | None = None

The object’s title.

field title_is_positioned_on_top : bool = True

When true, the title appears above the object; when false, the title appears below the object, above the caption if there is one. Defaults to true. Keynote ignores this when the object has none, or when it’s hidden with Label.is_visible set to false; 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_visible set to false, 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 geometry must be present. If absent, Keynote assume this shape to be a rectangle the same size as geometry.

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 is none.

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 is none.

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 stroke : Stroke = Stroke(line=Line())

The stroke that appears along the shape’s path.

field opacity : float = 1

The shape’s opacity, in the range 0 to 1.

field shadow : Override[Shadow] = Override.not_set()

The shadow beneath the shape.

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 text : Text | None = None

The text inside the shape.

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.

field position : Position [Required]

The top-left corner of the rectangle.

field size : Size [Required]

The width and height of the rectangle.

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.

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 d attribute 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, path is treated as relative to this rectangle, and then stretched proportionally to cover the bounding box of the owner’s geometry (Image.Mask.geometry for 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 when space differs 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, space must 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 empty for no stroke or border.

field empty : Literal[True] | None = None

No stroke or border.

field frame : Frame | None = None

A border drawn as a rectangular picture frame.

field line : Line | None = None

A stroke or border drawn as a line in one of several styles.

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 color : Color | None = None

The color of the stroke. If absent, the stroke is black.

field width : float = 1

The width of the stroke, in points.

Constraints:
  • ge = 0.25

  • le = 100

field pattern : Pattern = Pattern.SOLID

The pattern of the stroke: solid, dashed, or one of several brush styles.

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_dash also rounds the line’s caps and joins, and a dashed line with round caps is written as round_dash regardless of its dash pattern. Without round caps, a dash pattern that doesn’t match one of these cases is written as short_dash.

A field accepts a member or its value, so Pattern.CALLIGRAPHY and '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.

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 name : Name [Required]

The name of the picture frame.

field scale_percent : float = 100

The scale applied to the picture frame artwork, as a percentage, in the range 10 to 100. Some picture frames have an effective minimum higher than 10%, and a smaller value is raised to that minimum.

Constraints:
  • ge = 10

  • le = 100

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.ANTIQUE and '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'

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 by line_type. Because the line’s position and size follow from the route, geometry only 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 geometry property. If this property is absent, images, movies, and groups default to true, and other objects to false.

field description : str | None = None

The accessibility description for the object, read aloud by assistive technologies such as VoiceOver.

field line_type : LineType = LineType(straight=True)

The routing style of the connection line.

field tail : End [Required]

The tail end of the connection line.

field head : End [Required]

The head end of the connection line.

field stroke : Stroke = Stroke(line=Line())

The stroke used to draw the connection line.

field opacity : float = 1

The opacity of the connection line, in the range 0 to 1.

field shadow : Override[Shadow] = Override.not_set()

The shadow shown beneath the connection line.

field reflection : Reflection | None = None

The reflection shown for the connection line.

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.

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_point is effectively required: if a line’s tail or head leaves it out, the line is dropped, even if that end supplies an anchor.

field end_point : Position | None = None

Where this end of the line stops, unless anchor attaches it to an object. Although it’s marked optional, omitting it drops the whole line, even when anchor is present. For an attached end, give the object’s center, so a curved line bows where its line_type puts 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 anchor : Anchor | None = None

The object this end attaches to. If it’s absent, the end is unattached and stays at end_point.

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_point and a warning is reported. An end connected to the object that fills the title, body, or slide_number placeholder, or a layout’s object placeholder, is also left unconnected, but no warning is reported.

field magnet : Magnet = Magnet(center=True)

Which point on the connected object this end attaches to.

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.