shape¶

        classDiagram
  BaseException <|-- Exception
  CachedClass <|-- LinePath
  CachedClass <|-- ShapeType
  Curve <|-- CircleArc
  Curve <|-- CubicBezier
  Curve <|-- EllipseArc
  Curve <|-- QuadraticBezier
  Exception <|-- CharmyShapeError
  LinePath <|-- Curve
  LinePath <|-- Line
  LinePath <|-- PolyLine
  ShapeType <|-- ShapeGroup
  ShapeType <|-- SingleShape
  SingleShape <|-- AnyShape
  SingleShape <|-- Rect
  SingleShape <|-- RoundRect

Charmy lines and shapes APIs.

This module implements Charmy's ability to express and draw lines and shapes.

Lines¶

Lines are divided into following types: lines for straight lines, polylines, circle arcs, ellipse arcs (not implemented), quadratic Bezier curves and cubic Bezier curves.

Each LinePath object can either be used to express a path, to be used to express a part of a shape, or to be drawn on a window directly. Paths expressed by lines may be used in animations in the future; shapes expressed by a list of lines can be drawn (see Shape section below); lines that are drawn directly are called DrawnLine, which can have their texture and line width be specified and adjusted.

Shapes¶

In Charmy, all shapes can be expressed by a sequence of lines. Shapes are divided into following types: Any Shape, Rect, RoundedRect. Backends that does not support drawing any_shape (line-sequence-expressed shapes) will be able to draw some of the other shape types directly using its renderer's API.

Each Shape object can either be used to express a shape of a widget or be drawn on a window. Shapes that are drawn on windows are called DrawnShape, which can have their inside texture, border width, and border texture be specified and adjusted.

class charmy.styles.shape.LinePath¶

基类：CachedClass

Base class of all line paths.

type: ClassVar[str] = 'line_path_class'¶

__init__()¶

property start_point: tuple[int, int]¶

property end_point: tuple[int, int]¶

fallback(_from: list[type[LinePath]] = []) → list[LinePath]¶

Fallback ability of the line. For final fallback, warn that the line cannot be drawn.

参数:: _from -- Fallback path, for internal use
Return value:: Alternative sequence of lines that represents or simulate the same line

property boundary: tuple[tuple[int, int], tuple[int, int]]¶: Rectangle boundary of the line.

static find_class_by_type(type_name: str) → type[LinePath] | None¶

Find a line class by line type, return None if not found.

参数:: type_name -- Line type in string

static from_json(json_content: dict[str, Any] | str) → LinePath¶

Create a shape object from json content.

This function is a static method of LinePath and its subclasses. It creates and returns a line object base on the JSON content given. This will be useful when loading line config from styles.

参数:: json_content -- The JSON content, either Python dict or raw string data

JSON Format¶

Lines can be represented in JSON in a structured way. Each JSON data must has a type key that defines the type of the line, and also other keys and values that specify the params for that line. The following is an example for polylines.

{
"type": "polyline", 
"points": [
    (10, 10), (100, 50), (50, 100)
],
}

class charmy.styles.shape.Line(points: list[tuple[int, int]] | Var[list[tuple[int, int]]])¶

基类：LinePath

Represents lines.

参数:: points -- List of the 2 points that determines the line

type: ClassVar[str] = 'line'¶

points: list[tuple[int, int]] | Var[list[tuple[int, int]]]¶

fallback(_from: list[type[LinePath]] = []) → list[LinePath]¶

Convert line to single polyline.

参数:: _from -- Fallback path, for internal use
Return value:: Alternative sequence of lines that represents or simulate the same line

to_polyline() → PolyLine¶: Convert line to polyline.

property start_point: tuple[int, int]¶: Starting point of the line.

property end_point: tuple[int, int]¶: Ending point of the line

property boundary: PropType¶

__init__(points: list[tuple[int, int]] | Var[list[tuple[int, int]]]) → None¶

class charmy.styles.shape.PolyLine(points: list[tuple[int, int]] | Var[list[tuple[int, int]]])¶

基类：LinePath

Represents polylines.

参数:: points -- List of points that determines the line(s)

type: ClassVar[str] = 'polyline'¶

points: list[tuple[int, int]] | Var[list[tuple[int, int]]]¶

fallback(_from: list[type[LinePath]] = []) → Sequence[LinePath]¶

Convert polyline to list of lines.

参数:: _from -- Fallback path, for internal use
Return value:: Alternative sequence of lines that represents or simulate the same line

to_lines() → list[Line]¶: Convert self to lines segments.

static join(lines: list[PolyLine | Line]) → PolyLine¶: Join multiple lines / polylines to one single polyline.

property start_point: tuple[int, int]¶: Start point of this polyline.

property end_point: tuple[int, int]¶: End point of this polyline

property boundary: PropType¶

__init__(points: list[tuple[int, int]] | Var[list[tuple[int, int]]]) → None¶

class charmy.styles.shape.Curve¶

基类：LinePath

Class representing curves, should not be used in rendering.

Tips¶

For self-defined curves, consider using sequence of quadratic Beziers.

__init__() → None¶

draw()¶

abstractmethod flatten(tolerance: int = 15) → PolyLine¶

class charmy.styles.shape.CircleArc(center: tuple[int, int] | Var[tuple[int, int]], radius: int | Var[int], start_orient: int | Var[int], end_orient: int | Var[int])¶

基类：Curve

Represents circle arcs.

Coordinate System¶

0° is at the top (positive Y direction)
Angles increase clockwise

param center:: Coordinates of the center of the circle
param radius:: Radius of the circle, in integer
param start_orient:: Starting orientation in integer degrees
param end_orient:: Ending orientation in integer degrees

type: ClassVar[str] = 'circle_arc'¶

center: tuple[int, int] | Var[tuple[int, int]]¶

radius: int | Var[int]¶

start_orient: int | Var[int]¶

end_orient: int | Var[int]¶

property start_point: tuple[int, int]¶

property end_point: tuple[int, int]¶

fallback(_from: list[type[LinePath]] = []) → list[LinePath]¶: Simulates the circle arc using a sequence of Cubic Bezier curves.

flatten(tolerance: float = 15.0) → PolyLine¶: Flatten the circle arc into a PolyLine approximation.

property boundary: PropType¶

__init__(center: tuple[int, int] | Var[tuple[int, int]], radius: int | Var[int], start_orient: int | Var[int], end_orient: int | Var[int]) → None¶

基类：Curve

Represents arcs trimmed from ellipses.

Note that this is NOT IMPLEMENTED and NOT PLANNED currently. You may see this as avandoned codes.

参数:

center -- Coordinates of the center of the oval
v_radius -- Vertical radius in integer
h_radius -- Horizontal radius in integer
rotation -- Rotation in integer degrees
start_orient -- Starting orientation in integer degrees
end_orient -- Ending orientation in integer degrees

type: ClassVar[str] = 'ellipse_arc'¶

center: tuple[int, int] | Var[tuple[int, int]]¶

v_radius: int | Var[int]¶

h_radius: int | Var[int]¶

rotation: int | Var[int]¶

start_orient: int | Var[int]¶

end_orient: int | Var[int]¶

__init__(center: tuple[int, int] | Var[tuple[int, int]], v_radius: int | Var[int], h_radius: int | Var[int], rotation: int | Var[int], start_orient: int | Var[int], end_orient: int | Var[int]) → None¶

class charmy.styles.shape.QuadraticBezier(points: list[tuple[int, int]] | Var[list[tuple[int, int]]])¶

基类：Curve

Represents quadratic Bezier curves.

参数:: points -- List of the 3 points that determines the curve.

type: ClassVar[str] = 'quadratic_bezier'¶

points: list[tuple[int, int]] | Var[list[tuple[int, int]]]¶

property start_point: tuple[int, int]¶

property end_point: tuple[int, int]¶

fallback(_from: list[type[LinePath]] = []) → list[LinePath]¶

Convert quadratic Bezier curves to cubic.

参数:: _from -- Fallback path, for internal use
Return value:: Alternative sequence of lines that represents or simulate the same line

flatten(tolerance: float = 15.0) → PolyLine¶: Flatten the quadratic Bezier curve into a PolyLine approximation.

property boundary: PropType¶

__init__(points: list[tuple[int, int]] | Var[list[tuple[int, int]]]) → None¶

class charmy.styles.shape.CubicBezier(points: list[tuple[int, int]] | Var[list[tuple[int, int]]])¶

基类：Curve

Represents cubic Bezier curves.

The Points¶

Almost ame as SVG path, you should give the points in order of:

Starting point
1st control point
2nd control point
Ending point

param points:: List of the 3 points that determines the curve

type: ClassVar[str] = 'cubic_bezier'¶

points: list[tuple[int, int]] | Var[list[tuple[int, int]]]¶

property start_point: tuple[int, int]¶

property end_point: tuple[int, int]¶

flatten(tolerance: float = 15.0) → PolyLine¶: Flatten the cubic Bezier curve into a PolyLine approximation.

property boundary: PropType¶

__init__(points: list[tuple[int, int]] | Var[list[tuple[int, int]]]) → None¶

exception charmy.styles.shape.CharmyShapeError¶: 基类：Exception

class charmy.styles.shape.ShapeType(*args, **kwargs)¶

基类：CachedClass

Base class of shapes.

type: ClassVar[str] = 'shape_type'¶

__init__(*args, **kwargs)¶

abstract property boundary: tuple[tuple[int, int], tuple[int, int]]¶

class charmy.styles.shape.SingleShape¶

基类：ShapeType

Base class of all single shapes.

type: ClassVar[str] = 'single_shape'¶

__init__()¶

abstract property lines: list[LinePath]¶

property boundary: PropType¶

static find_class_by_type(type_name: str) → type[SingleShape] | None¶

Find a shape class by shape type, return None if not found.

参数:: type_name -- Shape type in string

static from_json(json_content: dict[str, Any] | str) → SingleShape¶

Create a shape object from json content.

This function is a static method of AnyShape and its subclasses. It creates and returns a shape object base on the JSON content given. This will be useful when loading shape config from styles.

参数:: json_content -- The JSON content, either Python dict or raw string data

JSON Format¶

Shapes can be represented in JSON in a structured way. Each JSON data must has a type key that defines the type of the shape, and also other keys and values that specify the params for that shape. The following is an example for rectangles.

{
"type": "rect", 
"pos": (50, 50), 
"size": (100, 100), 
}

static from_profile_value(profile_value: dict[str, Any] | SingleShape) → SingleShape¶

Load shape from profile value.

If is JSON, load from JSON, otherwise return as-is.

flatten(tolerance: int = 15) → PolyLine¶: Convert all curve edges to polyline and merge the shape into a single polyline.

class charmy.styles.shape.AnyShape(lines: Sequence[LinePath | dict[str, Any]])¶

基类：SingleShape

Shapes made up with sequence of lines.

__init__(lines: Sequence[LinePath | dict[str, Any]])¶

To initialize and validate a shape.

参数:: lines -- The lines that form the shape

property lines: list[LinePath]¶: Lines that forms the AnyShape, converted into value if was set to var.

class charmy.styles.shape.Rect(pos: tuple[int, int] | Var[tuple[int, int]], size: tuple[int, int] | Var[tuple[int, int]])¶

基类：SingleShape

Represents rectangles in Charmy.

参数:

position -- The position of the rectangle
size -- The size of the rectangle

type: ClassVar[str] = 'rect'¶

pos: tuple[int, int] | Var[tuple[int, int]]¶

size: tuple[int, int] | Var[tuple[int, int]]¶

property lines: PropType¶

property boundary: PropType¶

__init__(pos: tuple[int, int] | Var[tuple[int, int]], size: tuple[int, int] | Var[tuple[int, int]]) → None¶

基类：SingleShape

Represents round-corner rectangles in Charmy.

参数:

position -- The position of the round-corner rectangle
size -- The size of the round-corner rectangle
radius -- Radius of the round corners or of each corner, in px

type: ClassVar[str] = 'round_rect'¶

pos: tuple[int, int] | Var[tuple[int, int]]¶

size: tuple[int, int] | Var[tuple[int, int]]¶

radius: int | tuple[int, int, int, int] | Var[int | tuple[int, int, int, int]]¶

property lines: PropType¶

property boundary: PropType¶

__init__(pos: tuple[int, int] | Var[tuple[int, int]], size: tuple[int, int] | Var[tuple[int, int]], radius: int | tuple[int, int, int, int] | Var[int | tuple[int, int, int, int]]) → None¶

class charmy.styles.shape.ShapeGroup(shapes: Sequence[AnyShape | ShapeGroup])¶

基类：ShapeType

Complicated shapes formed by a group of AnyShape.

type: ClassVar[str] = 'shape_group'¶

__init__(shapes: Sequence[AnyShape | ShapeGroup]) → None¶: To express a composite shape.

property shapes: Sequence[AnyShape]¶: Shapes that make up this shape group

property boundary: PropType¶