Class Line

A line element that draws a straight or curved line segments between the given points. This class represents a line element in the drawing canvas. It provides functionality for creating and manipulating straight pr curved lines with specified configurations for styling and positioning.

[!WARNING] Do not instantiate this class directly. Use SceneBuilder.line() instead.

Methods

init

    def __init__(self, defaults: Defaults):

Initialize self. See help(type(self)) for accurate signature.

append

    def append(self, points: list[Point]) -> Self:

Appends points to the line.

Arguments

Name	Type	Description
`points`	`list[Point]`	A list of Point objects to append. Returns: Self: The instance of the class with updated points, width, and height.

arc

    def arc(self, x: float, y: float, radius: float, start_angle: float, angle_span: float) -> Self:

Adds an arc to the line. Approximates an arc between two points, given by the center of the arc, radius, start angle and angle span.

Arguments

Name	Type	Description
`x`	`float`	The x-coordinate of the center of the arc.
`y`	`float`	The y-coordinate of the center of the arc.
`radius`	`float`	The radius of the arc.
`start_angle`	`float`	The starting angle of the arc, in radians.
`angle_span`	`float`	The angle span of the arc, in radians.

Returns

Type: Self

The instance of the class for method chaining.

background

    def background(self, color: str | Color) -> Self:

Set the background (fill) color of the shape created by a closed line segments.

Arguments

Name	Type	Description
`color`	`str or Color`	The background color, specified as a hex string (#RRGGBB), a color name, or a Color object.

Returns

Type: Self

The instance of the class for method chaining.

center

    def center(self, *args) -> Self | tuple[float, float]:

Get or set the center coordinates of the element.

Arguments

Name	Type	Description
`*args`	`None`	Supports two signatures: 1. center() -> tuple[float, float] Returns the (x, y) coordinates of the center. 2. center(x, y) -> Self Sets the center to (x, y) and returns self for chaining.

Returns

Type: tuple[float, float] or Self

Depending on the arguments.

close

    def close(self):

Close the line by connecting the last point to the first point.

color

    def color(self, color: str | Color) -> Self:

Set the stroke (outline) color as #RRGGBB, color name or Color object.

Arguments

Name	Type	Description
`color`	`str or Color`	The color to set, specified as a hex string $RRGGBB, color name, or Color object.

Returns

Type: Self

The current instance of the AbstractStrokedElement class.

fill

    def fill(self, style: str) -> Self:

Set the fill style for the shape created by a closed line segments.

Arguments

Name	Type	Description
`style`	`str`	The fill style to be applied. Must be one of 'hachure', 'cross-hatch', or 'solid'.

Returns

Type: Self

The instance of the shape with the updated fill style.

Raises

ValueError: If the provided style is not one of 'hachure', 'cross-hatch', or 'solid'.

link

    def link(self, target: "str | AbstractElement") -> Self:

Establishes a link to the given target, which can be either a string URL or an AbstractElement instance.

Arguments

Name	Type	Description
`target`	`str or AbstractElement`	The target to link to. If it's an AbstractElement, a URL will be generated using its ID. If it's a string, it will be used directly as the link.

Returns

Type: Self

The instance of the current object with the updated link.

Raises

ValueError: If the target is neither a string nor an AbstractElement.

opacity

    def opacity(self, opacity: int) -> Self:

Set the opacity of the element.

Arguments

Name	Type	Description
`opacity`	`int`	The opacity value to set, must be in the range 0-100. 100 is fully opaque, 0 is fully transparent.

Returns

Type: Self

The instance of the element with updated opacity.

Raises

ValueError: If the opacity value is not within the range 0-100.

orbit

    def orbit(self, *args) -> Self:

Positions the element relative to a reference using polar coordinates. This method allows placing the element such that its center will be at (radius, angle) from a reference. The reference can be either another AbstractElement or a point (x, y).

Arguments

Name	Type	Description
`*args`	`None`	Supports two signatures: 1. orbit(element, radius, angle)
`element`	`AbstractElement`	The reference element to orbit around.
`radius`	`float`	The distance from the center of the reference.
`angle`	`float`	The angle to position the element at, in radians.

Returns

Type: Self

The instance of the element.

Raises

ValueError: If the arguments do not match the expected signatures.

points

    def points(self, points: list[Point]) -> Self:

Sets the points for the line and calculates the width and height.

Arguments

Name	Type	Description
`points`	`list[Point]`	A list of Point objects representing the coordinates of the line. Returns: Self: The instance of the class with updated points, width, and height.

position

    def position(self, x: float, y: float) -> Self:

Sets the position of the element.

Arguments

Name	Type	Description
`x`	`float`	The x-coordinate of the element.
`y`	`float`	The y-coordinate of the element.

Returns

Type: Self

The instance of the element with updated position.

prepend

    def prepend(self, points: list[Point]) -> Self:

Prepends points to the line.

Arguments

Name	Type	Description
`points`	`list[Point]`	A list of Point objects to prepend. Returns: Self: The instance of the class with updated points, width, and height.

rotate

    def rotate(self, angle: float) -> Self:

Rotate the element clockwise by a specified angle.

Arguments

Name	Type	Description
`angle`	`float`	The angle to rotate the element clockwise by, in radians.

Returns

Type: Self

The instance of the element after rotation.

roundness

    def roundness(self, roundness: str) -> Self:

Set the roundness style of the shape.

Arguments

Name	Type	Description
`roundness`	`str`	The roundness style to set. Acceptable values are: - "sharp": Sets the shape to have sharp corners. - "round": Sets the shape to have rounded corners.

Returns

Type: Self

The instance of the shape with the updated roundness style.

Raises

ValueError: If the provided roundness style is not "sharp" or "round".

size

    def size(self, width: float, height: float) -> Self:

Set the size of the shape.

Arguments

Name	Type	Description
`width`	`float`	The width of the shape.
`height`	`float`	The height of the shape.

Returns

Type: Self

The instance of the shape with the updated size.

sloppiness

    def sloppiness(self, value: int | str) -> Self:

Set the stroke sloppiness by int (0, 1, 2) or by string ('architect', 'artist', 'cartoonist').

Arguments

Name	Type	Description
`value`	`int or str`	The sloppiness value to set, specified as an integer (0, 1, 2) or a string ('architect', 'artist', 'cartoonist').

Returns

Type: Self

The current instance of the AbstractStrokedElement class.

Raises

ValueError: If an invalid sloppiness value is provided.

stroke

    def stroke(self, style: str) -> Self:

Set the stroke style (solid, dotted, dashed).

Arguments

Name	Type	Description
`style`	`str`	The stroke style to set, specified as 'solid', 'dotted', or 'dashed'.

Returns

Type: Self

The current instance of the AbstractStrokedElement class.

Raises

ValueError: If an invalid stroke style is provided.

thickness

    def thickness(self, thickness: int | str) -> Self:

Set the stroke thickness by int (1, 2, 3) or by string ('thin', 'bold', 'extra-bold').

Arguments

Name	Type	Description
`thickness`	`int or str`	The thickness to set, specified as an integer (1, 2, 3) or a string ('thin', 'bold', 'extra-bold').

Returns

Type: Self

The current instance of the AbstractStrokedElement class.

Raises

ValueError: If an invalid thickness value is provided.