Fills

Fill an area with a solid color, a gradient, or an image.

Fill

class creator_studio_doc_format.core.Fill(*, preset_identifier='', color=None, gradient=None, image=None, **extra_data)[source]

A style that fills an area with exactly one of a solid color, a gradient, or an image.

field color : Color | None = None

A solid color fill.

field gradient : Gradient | None = None

A gradient fill, either linear or radial.

field image : ImageFill | None = None

An image fill, with optional scale and tint.

Gradient

class creator_studio_doc_format.core.Gradient(*, preset_identifier='', is_advanced=False, stops, opacity=1, flavor, **extra_data)[source]

A fill with a continuous gradient between two or more colors.

field is_advanced : bool = False

Whether the gradient is an advanced gradient. It’s independent of the linear or radial flavor and doesn’t affect rendering.

field stops : list[Stop] [Required]

The color stops that define the gradient, ordered from the start of the gradient to its end. A gradient must have at least two stops. An array with fewer than two stops is padded to two on read; an empty one produces a fully transparent gradient. If a stop’s fraction isn’t greater than the previous stop’s, it’s shown immediately after the previous stop.

field opacity : float = 1

The opacity of the gradient, in the range 0 to 1.

Constraints:
  • ge = 0

  • le = 1

field flavor : Flavor [Required]

The kind of gradient, linear or radial, along with the geometry that positions it.

Stop

class creator_studio_doc_format.core.Stop(*, preset_identifier='', color, fraction, inflection=0.5, **extra_data)[source]

One color in the gradient, and its position along it.

field color : Color [Required]

The stop’s color.

field fraction : float [Required]

The position of the stop within the entire gradient, in the range 0 to 1. Each stop must have its position at or after the position of the previous stop.

Constraints:
  • ge = 0

  • le = 1

field inflection : float = 0.5

A position between the stop and the following stop that defines where the halfway blend of the two stops’ colors falls, as a fraction of the distance between them. An inflection of 0.5 blends two stops evenly; lower values pull the blend toward the stop, and higher values toward the following stop. Has no effect on the last stop.

Constraints:
  • ge = 0

  • le = 1

Flavor

class creator_studio_doc_format.core.Flavor(*, preset_identifier='', linear=None, radial=None, **extra_data)[source]

A method for laying out a gradient’s stops over the area being filled.

Each case’s value gives the geometry that positions the stops.

field linear : Linear | None = None

A gradient that varies along a straight line between its stops.

field radial : Radial | None = None

A gradient that spreads outward from a center point.

Linear

class creator_studio_doc_format.core.Linear(*, preset_identifier='', angle, start_point=None, end_point=None, base_natural_size=None, **extra_data)[source]

A gradient that lays out its stops along a straight line.

angle alone fits the line to the filled shape’s bounds, so the whole stop range is visible. start_point, end_point, and base_natural_size place it exactly, possibly running past those bounds; the points are in the shape’s untransformed space, in points with y increasing downward, and rescale when the object’s size differs from base_natural_size. Those three are read only together: with any of them missing, the gradient falls back to angle and discards the points.

field angle : float [Required]

The angle in degrees at which the gradient runs, in the range 0 to 360 (exclusive) measured counterclockwise with 0 corresponding to horizontal left-to-right. Ignored if start_point, end_point, and base_natural_size are all present; angle remains the fallback for version 1.0 readers, which predate those properties.

Constraints:
  • ge = 0

  • le = 360

field start_point : Position | None = None

If present, the starting point of the line along which the gradient’s colors change, relative to a rectangle defined by base_natural_size. If it’s present, it must be combined with end_point and base_natural_size; when all three are present, they take precedence over angle. Version 1.0 readers ignore it and render from angle.

field end_point : Position | None = None

If present, the end point of the line along which the gradient’s colors change, relative to a rectangle defined by base_natural_size. If it’s present, it must be combined with start_point and base_natural_size. For details, see start_point.

field base_natural_size : Size | None = None

If present, the size of the rectangle that start_point and end_point are relative to. When filling an area, the gradient’s start and end points are transformed so that this size covers the filled area. For details, see start_point.

Radial

class creator_studio_doc_format.core.Radial(*, preset_identifier='', start_point, end_point, base_natural_size, **extra_data)[source]

A gradient that spreads its stops outward from a center point, with a second point fixing the radius and the direction of the outer edge.

Both points are in the filled shape’s untransformed space, in points with y increasing downward; base_natural_size is the size that space was captured at, so the gradient rescales when the object’s size differs from it.

field start_point : Position [Required]

The center point of the radial gradient, relative to a rectangle defined by base_natural_size.

field end_point : Position [Required]

A point on the outer edge of the radial gradient, relative to a rectangle defined by base_natural_size. Together with start_point, it sets the gradient’s radius and direction.

field base_natural_size : Size [Required]

The size of the rectangle that start_point and end_point are relative to. When filling an area, the gradient’s start and end points are transformed so that this size covers the filled area.

ImageFill

class creator_studio_doc_format.core.ImageFill(*, preset_identifier='', resource, technique, scale_percent=100, tint_color=None, **extra_data)[source]

An image that the reader uses to fill an area.

field resource : Resource [Required]

The resource containing the image fill’s data.

field technique : Technique [Required]

How the image fill covers the filled area.

field scale_percent : float = 100

A scale applied to the image resource’s natural size, as a percentage in the range 10 to 200; a value of 100 shows the image at its natural size. Used only when technique is natural_size or tile.

Constraints:
  • ge = 10

  • le = 200

field tint_color : Color | None = None

A color laid over the image, usually with an opacity less than 1. The default is none.

Technique

class creator_studio_doc_format.core.Technique(str, Enum)[source]

The technique the reader uses to fit the image to the fill area.

The technique also determines whether the image keeps its aspect ratio: one technique distorts the image to the area, two preserve the ratio (cropping the overhang or leaving the area showing through), and two show the image at a size of its own.

A field accepts a member or its value, so Technique.NATURAL_SIZE and 'natural_size' are the same. The member’s name as a string isn’t accepted.

NATURAL_SIZE = 'natural_size'

Draws the image once at its own size, scaled by Fill.ImageFill.scale_percent, centered in the area and clipped by it, so a larger image is cropped on all four sides and a smaller one leaves the area showing around it.

SCALE_TO_FILL = 'scale_to_fill'

Draws the image so that it keeps its aspect ratio and completely covers the filled area, cropping what overhangs on the longer axis.

SCALE_TO_FIT = 'scale_to_fit'

Draws the image so that it keeps its aspect ratio and fits completely within the filled area, which shows through on the two sides where the image falls short.

STRETCH = 'stretch'

Draws the image stretched over the filled area, scaling its width and height independently and distorting it unless the area already shares the image’s proportions.

TILE = 'tile'

Repeats the image at its own size, scaled by Fill.ImageFill.scale_percent, to cover the area. The first tile is placed at the filled area’s top-left corner.