开罗上下文

类上下文（）

class cairo.Context(target: _SomeSurface)

语境 是在使用cairo绘图时使用的主要对象。要使用cairo进行绘制，请创建 语境 ，设置目标曲面，并为 语境 ，创建具有以下功能的形状 Context.move_to() 和 Context.line_to() ，然后用 Context.stroke() 或 Context.fill() .

语境 可以通过 Context.save() . 然后可以安全地更改它们，而不会丢失当前状态。使用 Context.restore() 恢复到保存状态。

__init__(target: _SomeSurface) → None

参数:

target -- 目标 Surface 对于上下文

加薪:

MemoryError 如果没有记忆

创建新的 语境 将所有图形状态参数设置为默认值，并使用 目标 作为目标表面。目标表面应该用后端特定的函数构造，例如 ImageSurface （或任何其他cairo后端曲面创建变量）。

append_path(path: Path) → None

参数:

path -- Path 附加

附加 path 到当前路径。这个 path 可以是以下值之一的返回值 Context.copy_path() 或 Context.copy_path_flat() 或者可以手动构造（在C中）。

arc(xc: float, yc: float, radius: float, angle1: float, angle2: float) → None

参数:

• xc -- 弧中心的X位置

• yc -- 弧中心的Y位置

• radius -- 弧的半径

• angle1 -- 以弧度表示的起始角

• angle2 -- 以弧度表示的端点角度

添加给定的圆弧 半径 到当前路径。弧的中心在（ XC，YC ）开始于 角1 继续向角度增加的方向移动 角2 .如果 角2 小于 角1 将逐步增加2 直到它大于 角度1*

如果存在当前点，则会在路径中添加一个初始线段，以将当前点连接到圆弧的起点。如果不需要这个初始行，可以通过调用 Context.new_sub_path() 打电话之前 Context.arc() .

角度是以弧度测量的。0.0的角度是在正x轴的方向上（在用户空间中）。圆周率/2.0弧度（90度）的角度在正Y轴的方向上（在用户空间中）。角度从正X轴向正Y轴方向增加。所以对于默认的变换矩阵，角度是顺时针方向增加的。

要从度转换为弧度，请使用 degrees * (math.pi / 180) .

此函数给出了角度增加方向上的弧；请参见 Context.arc_negative() 以得到角度递减方向的弧。

弧在用户空间是圆形的。要实现椭圆弧，可以在x和y方向上按不同的数量缩放当前变换矩阵。例如，在框中绘制椭圆 x，y，宽度，高度 ：：

ctx.save()
ctx.translate(x + width / 2., y + height / 2.)
ctx.scale(width / 2., height / 2.)
ctx.arc(0., 0., 1., 0., 2 * math.pi)
ctx.restore()

arc_negative(xc: float, yc: float, radius: float, angle1: float, angle2: float) → None

参数:

• xc -- 弧中心的X位置

• yc -- 弧中心的Y位置

• radius -- 弧的半径

• angle1 -- 以弧度表示的起始角

• angle2 -- 以弧度表示的端点角度

添加给定的圆弧 半径 到当前路径。弧的中心在（ XC，YC ）开始于 角1 然后朝着减小角度的方向前进 角2 .如果 角2 大于 角1 它将逐渐减少2 直到它小于 角度1*

见 Context.arc() 了解更多详细信息。此函数仅在两个角度之间的圆弧方向上不同。

clip() → None

通过将当前剪辑区域与当前路径相交来建立新的剪辑区域，因为它将由 Context.fill() 根据目前的情况 fill rule （见 Context.set_fill_rule() ）

后 clip() ，当前路径将从 Context .

当前剪辑区域通过有效地屏蔽对当前剪辑区域之外的曲面的任何更改来影响所有绘图操作。

调用 clip() can only make the clip region smaller, never larger. But the current clip is part of the graphics state, so a temporary restriction of the clip region can be achieved by calling clip() within a Context.save()/Context.restore() 一对。增加剪辑区域大小的唯一其他方法是 Context.reset_clip() .

clip_extents() → Tuple[float, float, float, float]

返回:

（x1，y1，x2，y2），全浮式

• x1 ：结果范围的左侧

• y1 ：结果范围的顶部

• x2 ：结果范围的右侧

• y2 ：结果范围的底部

以覆盖当前剪辑内区域的用户坐标计算边界框。

在 1.4 版本加入.

clip_preserve() → None

通过将当前剪辑区域与当前路径相交来建立新的剪辑区域，因为它将由 Context.fill() 根据目前的情况 fill rule （见 Context.set_fill_rule() ）

不像 Context.clip() ， clip_preserve() 保留中的路径 Context .

当前剪辑区域通过有效地屏蔽对当前剪辑区域之外的曲面的任何更改来影响所有绘图操作。

调用 clip_preserve() can only make the clip region smaller, never larger. But the current clip is part of the graphics state, so a temporary restriction of the clip region can be achieved by calling clip_preserve() within a Context.save()/Context.restore() 一对。增加剪辑区域大小的唯一其他方法是 Context.reset_clip() .

close_path() → None

将一个线段添加到从当前点到当前子路径开始的路径中（传递给 Context.move_to() ，并关闭此子路径。调用后，当前点将位于子路径的连接端点。

行为 close_path() 不同于简单的呼叫 Context.line_to() 在冲程的情况下使用等效坐标。当一个封闭的子路径被敲击时，子路径的末端没有盖子。相反，有一个连接子路径的最终和初始段的线连接。

如果调用之前没有当前点 close_path() ，此功能无效。

注：从开罗1.2.4版开始，任何调用 close_path() 将在关闭路径元素后立即将显式移动到路径中（可以在中看到 Context.copy_path() 例如）。在某些情况下，这可以简化路径处理，因为在处理过程中可能不需要保存“最后一次移动到点”，因为在关闭路径之后立即移动到点将提供该点。

copy_clip_rectangle_list() → List[Rectangle]

返回:

当前剪辑区域作为用户坐标中的矩形列表。返回的列表 Rectangle

在 1.4 版本加入.

copy_page() → None

为支持多页但不清除的后端发出当前页，因此当前页的内容也将保留到下一页。使用 Context.show_page() 如果你想在发射后得到一个空白页。

这是一个简单调用 Surface.copy_page() 在 上下文 目标。

copy_path() → Path

返回:

Path

加薪:

MemoryError 如果没有记忆

创建当前路径的副本并将其作为 Path .

copy_path_flat() → Path

返回:

Path

加薪:

MemoryError 如果没有记忆

获取当前路径的扁平副本，并将其作为 Path .

这个功能就像 Context.copy_path() 除了路径中的任何曲线都将采用分段线性近似法进行近似（精确到当前公差值内）。也就是说，结果保证没有任何cairo-path-curve-to类型的元素，取而代之的是一系列cairo-path-line-to元素。

curve_to(x1: float, y1: float, x2: float, y2: float, x3: float, y3: float) → None

参数:

• x1 -- 第一个控制点的X坐标

• y1 -- 第一个控制点的Y坐标

• x2 -- 第二控制点的X坐标

• y2 -- 第二控制点的Y坐标

• x3 -- 曲线末端的X坐标

• y3 -- 曲线末端的Y坐标

将三次B_zier样条线添加到从当前点到位置的路径中 （x3、y3） 在用户空间坐标中，使用 （x1，y1） 和 （x2、y2） 作为控制点。在这个调用之后，当前点将 （x3、y3） .

如果调用之前没有当前点 curve_to() 此函数的行为将类似于前面有一个对 ctx.move_to(x1, y1) .

device_to_user(x: float, y: float) → Tuple[float, float]

参数:

• x -- 坐标X值

• y -- 坐标Y值

返回:

（x，y），两个浮动

通过将给定点乘以当前转换矩阵（CTM）的倒数，将坐标从设备空间转换为用户空间。

device_to_user_distance(dx: float, dy: float) → Tuple[float, float]

参数:

• dx -- 距离向量的x分量

• dy -- 距离向量的y分量

返回:

（dx，dy），两个浮球

将距离向量从设备空间转换为用户空间。此功能类似于 Context.device_to_user() 但是，在转换时会忽略逆CTM的转换分量 （Dx，Dy） .

fill() → None

根据当前路径填充当前路径的绘图运算符 fill rule ，（每个子路径在填充之前都是隐式关闭的）。后 fill() ，当前路径将从 Context . 见 Context.set_fill_rule() 和 Context.fill_preserve() .

fill_extents() → Tuple[float, float, float, float]

返回:

（x1，y1，x2，y2），全浮式

• x1 ：结果范围的左侧

• y1 ：结果范围的顶部

• x2 ：结果范围的右侧

• y2 ：结果范围的底部

在用户坐标中计算一个边界框，该边界框覆盖了受 Context.fill() 给定当前路径和填充参数的操作。如果当前路径为空，则返回一个空矩形（0,0,0,0）。不考虑表面尺寸和剪切。

与…形成对比 Context.path_extents() ，这是相似的，但对于某些没有墨水区域的路径（例如简单的线段）返回非零范围。

注意 fill_extents() 必须根据填充规则做更多的工作来计算精确的墨区，所以 Context.path_extents() 如果需要非墨水路径范围，则可能更适合于性能。

见 Context.fill() ， Context.set_fill_rule() 和 Context.fill_preserve() .

fill_preserve() → None

根据当前路径填充当前路径的绘图运算符 fill rule ，（每个子路径在填充之前都是隐式关闭的）。不像 Context.fill() ， fill_preserve() 保留中的路径 Context .

见 Context.set_fill_rule() 和 Context.fill() .

font_extents() → Tuple[float, float, float, float, float]

返回:

（上升，下降，高度，最大前进，最大前进），所有浮动

获取当前选定字体的字体范围。

get_antialias() → Antialias

返回:

当前抗锯齿模式，由设置 Context.set_antialias() .

get_current_point() → Tuple[float, float]

返回:

（x，y），两个浮动

• x ：当前点的X坐标

• y ：当前点的Y坐标

获取当前路径的当前点，该点在概念上是该路径迄今为止到达的最后一个点。

当前点在用户空间坐标系中返回。如果没有定义的当前点，或者如果 Context 处于错误状态， x 和 y 都将设置为0.0。可以提前用 Context.has_current_point() .

大多数路径构建函数都会更改当前点。有关它们如何影响当前点的详细信息，请参见以下内容： Context.new_path() ， Context.new_sub_path() ， Context.append_path() ， Context.close_path() ， Context.move_to() ， Context.line_to() ， Context.curve_to() ， Context.rel_move_to() ， Context.rel_line_to() ， Context.rel_curve_to() ， Context.arc() ， Context.arc_negative() ， Context.rectangle() ， Context.text_path() ， Context.glyph_path() 。

某些函数使用并更改当前点，但不更改当前路径： Context.show_text() .

一些函数取消设置当前路径，因此，当前点： Context.fill() ， Context.stroke() .

get_dash() → Tuple[List[float], float]

返回:

（短划线，偏移）

• 破折号 ：以短划线数组的元组形式返回值

• 抵消 ：返回当前短划线偏移的浮点值

获取当前短划线数组。

在 1.4 版本加入.

get_dash_count() → int

返回:

破折号数组的长度，如果没有设置破折号数组，则为0。

也见 Context.set_dash() 和 Context.get_dash() .

在 1.4 版本加入.

get_fill_rule() → FillRule

返回:

当前填充规则，由设置 Context.set_fill_rule() .

get_font_face() → FontFace

返回:

当前 FontFace 对于 Context .

get_font_matrix() → Matrix

返回:

当前 Matrix 对于 Context .

见 Context.set_font_matrix() .

get_font_options() → FontOptions

返回:

当前 FontOptions 对于 Context .

检索通过设置的字体呈现选项 Context.set_font_options() . 请注意，返回的选项不包括从基础曲面派生的任何选项；它们实际上是传递给 Context.set_font_options() .

get_group_target() → Surface

返回:

目标 Surface .

获取当前目标 Surface 对于 Context . 这是传递到的原始目标曲面 Context 或当前组的目标图面（由最近调用开始） Context.push_group() 或 Context.push_group_with_content() .

在 1.2 版本加入.

get_hairline() → bool

返回:

是否设置发际线模式。

返回是否设置细线模式，由设置 Context.set_hairline() 。

在 1.23 版本加入: 仅适用于开罗1.17.6+

get_line_cap() → LineCap

返回:

当前线帽样式，由设置 Context.set_line_cap() .

get_line_join() → LineJoin

返回:

当前线条连接样式，由设置 Context.set_line_join() .

get_line_width() → float

返回:

当前线条宽度

此函数返回当前行宽值，该值与 Context.set_line_width() . 请注意，即使CTM在调用 Context.set_line_width() 和 get_line_width() .

get_matrix() → Matrix

返回:

电流变换 Matrix （CTM）

get_miter_limit() → float

返回:

当前斜接限制，由设置 Context.set_miter_limit() .

get_operator() → Operator

返回:

当前的合成运算符 Context .

get_scaled_font() → ScaledFont

返回:

当前 ScaledFont 对于一个 Context .

在 1.4 版本加入.

get_source() → Pattern

返回:

电流源 Pattern 对于一个 Context .

get_target() → _SomeSurface

返回:

目标 Surface 对于 Context

get_tolerance() → float

返回:

当前公差值，由设置 Context.set_tolerance()

glyph_extents(glyphs: Sequence[Glyph]) → TextExtents

参数:

glyphs -- 字形，一系列 Glyph

获取字形数组的范围。范围描述了一个用户空间矩形，它包含glyph的“inked”部分（它们将由 Context.show_glyphs() ）此外，x撊advance和y撊advance值指示当前点的提前量。 Context.show_glyphs() .

请注意，空白标志符号不会影响矩形的大小（extents.width和extents.height）。

glyph_path(glyphs: Sequence[Glyph]) → None

参数:

glyphs -- 要显示的标志符号，一系列 Glyph

将字形的闭合路径添加到当前路径。生成的路径如果被填充，将达到类似于 Context.show_glyphs() .

has_current_point() → bool

返回:

如果在当前路径上定义了当前点，则为True。看见 Context.get_current_point() 有关当前点的详细信息，请参阅。

在 1.6 版本加入.

identity_matrix() → None

重置当前转换 Matrix （ctm）通过设置它等于单位矩阵。也就是说，用户空间和设备空间轴将对齐，一个用户空间单元将转换为一个设备空间单元。

in_clip(x: float, y: float) → bool

参数:

• x -- 待测点的X坐标

• y -- 测试点的Y坐标

返回:

True 如果点在里面，或者 False 如果在外面。

测试给定点是否位于通过当前剪辑可见的区域内，即将由 paint() 操作。

见 clip() 和 clip_preserve() .

在 1.12.0 版本加入.

in_fill(x: float, y: float) → bool

参数:

• x -- 待测点的X坐标

• y -- 测试点的Y坐标

返回:

如果该点位于受 Context.fill() 给定当前路径和填充参数的操作。不考虑表面尺寸和剪切。

见 Context.fill() ， Context.set_fill_rule() 和 Context.fill_preserve() .

in_stroke(x: float, y: float) → bool

参数:

• x -- 待测点的X坐标

• y -- 测试点的Y坐标

返回:

如果该点位于受 Context.stroke() 给定当前路径和行程参数的操作。不考虑表面尺寸和剪切。

见 Context.stroke() ， Context.set_line_width() ， Context.set_line_join() ， Context.set_line_cap() ， Context.set_dash() 和 Context.stroke_preserve() .

line_to(x: float, y: float) → None

参数:

• x -- 新行末尾的X坐标

• y -- 新行末尾的Y坐标

将一条线添加到从当前点到位置的路径中 （x，y） 在用户空间坐标中。在这个调用之后，当前点将 （x，y） .

如果调用之前没有当前点 line_to() 此函数将表现为 ctx.move_to(x, y) .

mask(pattern: Pattern) → None

参数:

pattern -- 一 Pattern

使用alpha通道绘制当前源的绘图运算符。 模式 作为面具。（不透明区域 模式 与源一起绘制，透明区域不绘制。）

mask_surface(surface: Surface, x: float = 0.0, y: float = 0.0) → None

参数:

• surface -- 一 Surface

• x -- 放置原点的X坐标 表面

• y -- 放置原点的Y坐标 表面

使用alpha通道绘制当前源的绘图运算符。 表面 作为面具。（不透明区域 表面 与源一起绘制，透明区域不绘制。）

move_to(x: float, y: float) → None

参数:

• x -- 新位置的X坐标

• y -- 新位置的Y坐标

开始新的子路径。在这个调用之后，当前点将 （x，y） .

new_path() → None

清除当前路径。此调用之后将没有路径和当前点。

new_sub_path() → None

开始新的子路径。请注意，现有路径不受影响。此呼叫后将没有当前点。

在许多情况下，由于新的子路径经常以 Context.move_to() .

呼叫 new_sub_path() 当使用以下路径之一开始新的子路径时特别有用 Context.arc() 电话。这使得事情变得简单，因为不再需要手动计算圆弧的初始坐标来调用 Context.move_to() .

在 1.6 版本加入.

paint() → None

在当前剪辑区域的任意位置绘制当前源的绘图运算符。

paint_with_alpha(alpha: float) → None

参数:

alpha -- alpha值，介于0（透明）和1（不透明）之间

使用恒定alpha值的遮罩在当前剪辑区域内的任意位置绘制当前源的绘图运算符。 阿尔法 . 效果类似于 Context.paint() ，但使用alpha值淡出图形。

path_extents() → Tuple[float, float, float, float]

返回:

（x1，y1，x2，y2），全浮式

• x1 ：结果范围的左侧

• y1 ：结果范围的顶部

• x2 ：结果范围的右侧

• y2 ：结果范围的底部

计算用户空间坐标中覆盖当前路径上点的边界框。如果当前路径为空，则返回一个空矩形（0、0、0、0）。不考虑行程参数、填充规则、表面尺寸和剪裁。

与…形成对比 Context.fill_extents() 和 Context.stroke_extents() 它只返回将由相应的绘图操作“上色”的区域的范围。

结果 path_extents() 定义为等于 Context.stroke_extents() 在cairo.line_cap_round中，当线条宽度接近0.0时，（但从未到达由返回的空矩形） Context.stroke_extents() 行宽为0.0）。

具体来说，这意味着零区域子路径，例如 Context.move_to() ； Context.line_to() 段（即使是两个调用的坐标相同的退化情况）也将被视为对扩展数据块的贡献。但是，一个人 Context.move_to() 不会有助于 Context.path_extents() .

在 1.6 版本加入.

pop_group() → SurfacePattern

返回:

新创建的 SurfacePattern 包含对组执行的所有绘图操作的结果。

终止由调用开始的重定向 Context.push_group() 或 Context.push_group_with_content() 并返回包含对组执行的所有绘图操作的结果的新模式。

这个 pop_group() 函数调用 Context.restore() ，（平衡对 Context.save() 由 Context.push_group() 函数），使对图形状态的任何更改在组外都不可见。

在 1.2 版本加入.

pop_group_to_source() → None

终止由调用开始的重定向 Context.push_group() 或 Context.push_group_with_content() 并将生成的模式安装为源 Pattern 在给定的 Context .

此函数的行为等效于操作序列：

group = cairo_pop_group()
ctx.set_source(group)

但是更方便，因为它们不需要一个变量来存储指向模式的短期指针。

这个 Context.pop_group() 函数调用 Context.restore() ，（平衡对 Context.save() 由 Context.push_group() 函数），使对图形状态的任何更改在组外都不可见。

在 1.2 版本加入.

push_group() → None

临时将绘图重定向到称为组的中间曲面。重定向将持续到通过调用 Context.pop_group() 或 Context.pop_group_to_source() . 这些调用将任何绘图的结果作为模式（作为显式对象或设置为源模式）提供给组。

此组功能可以方便地执行中间合成。组的一个常见用途是将对象在组中呈现为不透明的（以便它们相互遮挡），然后将结果与半透明混合到目标上。

通过对 Context.push_group()/Context.pop_group() . 每次调用都将新的目标组推送/弹出到堆栈中。

这个 push_group() 函数调用 Context.save() 使对图形状态的任何更改在组外都不可见，（pop_group函数调用 Context.restore() ）

默认情况下，中间组将具有 cairo.Content 类型 cairo.Content.COLOR_ALPHA . 可以使用 Context.push_group_with_content() 相反。

例如，下面是如何使用半透明填充和绘制路径，但在笔划下不可见填充的任何部分：

ctx.push_group()
ctx.set_source(fill_pattern)
ctx.fill_preserve()
ctx.set_source(stroke_pattern)
ctx.stroke()
ctx.pop_group_to_source()
ctx.paint_with_alpha(alpha)

在 1.2 版本加入.

push_group_with_content(content: Content) → None

参数:

content (cairo.Content) -- 指示将要创建的组类型的内容

临时将绘图重定向到称为组的中间曲面。重定向将持续到通过调用 Context.pop_group() 或 Context.pop_group_to_source() . 这些调用将任何绘图的结果作为模式（作为显式对象或设置为源模式）提供给组。

组的内容类型为 内容 . 控制此内容类型的能力是此函数和 Context.push_group() 关于组渲染的更详细的描述，请参见。

在 1.2 版本加入.

rectangle(x: float, y: float, width: float, height: float) → None

参数:

• x -- 矩形左上角的X坐标

• y -- 矩形左上角的Y坐标

• width -- 矩形的宽度

• height -- 矩形的高度

将给定大小的闭合子路径矩形添加到位置处的当前路径 （x，y） 在用户空间坐标中。

此函数在逻辑上等价于：

ctx.move_to(x, y)
ctx.rel_line_to(width, 0)
ctx.rel_line_to(0, height)
ctx.rel_line_to(-width, 0)
ctx.close_path()

rel_curve_to(dx1: float, dy1: float, dx2: float, dy2: float, dx3: float, dy3: float) → None

参数:

• dx1 -- 到第一个控制点的X偏移

• dy1 -- 到第一个控制点的Y偏移

• dx2 -- 到第二个控制点的X偏移

• dy2 -- 到第二个控制点的Y偏移

• dx3 -- 到曲线末端的X偏移

• dy3 -- 到曲线末端的Y偏移

加薪:

cairo.Error 如果调用时没有当前点。

相对坐标版本 Context.curve_to() . 所有偏移都是相对于当前点的。将三次B_zier样条线添加到从当前点到从当前点偏移的点的路径中 （Dx3，Dy3） ，使用点偏移量 （Dx1，Dy1） 和 （Dx2，Dy2） 作为控制点。此调用之后，当前点将被偏移 （Dx3，Dy3） .

给定（x，y）的当前点， ctx.rel_curve_to(dx1, dy1, dx2, dy2, dx3, dy3) 逻辑上等价于 ctx.curve_to(x+dx1, y+dy1, x+dx2, y+dy2, x+dx3, y+dy3) .

rel_line_to(dx: float, dy: float) → None

参数:

• dx -- 到新行末尾的X偏移量

• dy -- 到新行末尾的Y偏移

加薪:

cairo.Error 如果调用时没有当前点。

相对坐标版本 Context.line_to() . 向从当前点到当前点偏移量为的点的路径添加一条线 （Dx，Dy） 在用户空间中。此调用之后，当前点将被偏移 （Dx，Dy） .

给定（x，y）的当前点， ctx.rel_line_to(dx, dy) 逻辑上等价于 ctx.line_to(x + dx, y + dy) .

rel_move_to(dx: float, dy: float) → None

参数:

• dx -- X偏移

• dy -- Y偏移

加薪:

cairo.Error 如果调用时没有当前点。

开始新的子路径。调用后，当前点将偏移 （Dx，Dy） .

给定（x，y）的当前点， ctx.rel_move_to(dx, dy) 逻辑上等价于 ctx.(x + dx, y + dy) .

reset_clip() → None

将当前剪辑区域重置为其原始的无限制状态。也就是说，将剪辑区域设置为包含目标曲面的无限大的形状。同样，如果无穷大太难把握，可以想象剪辑区域被重置为目标表面的精确边界。

注意，要重用的代码不应该调用 reset_clip() 因为它会导致更高级别的代码调用 clip() . 考虑使用 save() 和 restore() 围绕 clip() 作为临时限制剪辑区域的更强大的方法。

restore() → None

恢复 Context 到之前调用保存的状态 save() 并从保存的状态堆栈中删除该状态。

rotate(angle: float) → None

参数:

angle -- 用户空间轴旋转的角度（弧度）

通过以下方式旋转用户空间轴来修改当前转换矩阵（CTM） 角 弧度。轴的旋转发生在用户空间的任何现有转换之后。正角度的旋转方向是从正X轴到正Y轴。

save() → None

复制的当前状态 Context 并将其保存在保存状态的内部堆栈上。什么时候？ restore() 被称为 Context 将恢复到保存状态。多次呼叫 save() 和 restore() 可以嵌套；每次调用 restore() 从匹配的配对恢复状态 save() .

scale(sx: float, sy: float) → None

参数:

• sx -- X尺寸的比例因子

• sy -- Y尺寸的比例因子

通过按以下方式缩放X和Y用户空间轴来修改当前转换矩阵（CTM） sx 和 sy 分别。轴的缩放发生在用户空间的任何现有转换之后。

select_font_face(family: str, slant: FontSlant = Ellipsis, weight: FontWeight = Ellipsis) → None

参数:

• family -- 字体系列名称

• slant -- 字体的倾斜度，默认为 cairo.FontSlant.NORMAL .

• weight -- 字体的字体粗细，默认为 cairo.FontWeight.NORMAL .

注：该 select_font_face() 函数调用是cairo设计人员称之为“toy”文本API的一部分。它便于进行简短的演示和简单的程序，但不适合使用严肃文本的应用程序。

从简化描述中选择字体的系列和样式作为系列名称、斜线和粗细。开罗没有提供在系统上列出可用姓氏的操作（这是一个“玩具”，记住），但是标准的CSS2通用姓氏（“serif”、“sans-serif”、“cursive”、“fantasy”、“monospace”）可能会按预期工作。

有关“real”字体选择，请参阅您正在使用的字体后端的特定字体创建功能。（例如，如果您使用的是基于freetype的cairo ft字体后端，请参见cairo ft字体u face为u ft字体创建u face（）或cairo ft字体u face为u pattern（）创建u）生成的字体可以与cairo scalled字体u create（）和cairo set u scalled字体（）一起使用。

同样，当使用“real”字体支持时，您可以直接调用底层字体系统（如fontconfig或freetype），以执行诸如列出可用字体等操作。

预计大多数应用程序将需要与cairo结合使用更全面的字体处理和文本布局库（例如，pango）。

如果在不调用的情况下绘制文本 select_font_face() （或） set_font_face() 也不 set_scaled_font() ）的默认系列是特定于平台的，但本质上是“无衬线”。默认倾斜为 cairo.FontSlant.NORMAL ，默认权重为 cairo.FontWeight.NORMAL .

此函数等价于调用 ToyFontFace 然后 set_font_face() .

set_antialias(antialias: Antialias) → None

参数:

antialias -- 新的抗锯齿模式

设置用于绘制形状的栅格化器的抗锯齿模式。这个值是一个提示，特定的后端可能支持或不支持特定的值。目前，没有后端支持 cairo.Antialias.SUBPIXEL 绘制形状时。

请注意，此选项不影响文本呈现，请参见 FontOptions.set_antialias() .

set_dash(dashes: Sequence[float], offset: float = 0) → None

参数:

• dashes -- 一种序列，将开、关行程部分的交替长度指定为浮点数。

• offset -- 短划线模式中的偏移量，在该偏移量处笔划应开始，默认为0。

加薪:

cairo.Error 如果有任何值 破折号 为负，或者如果所有值都为0。

设置要由使用的短划线图案 stroke() . 破折号模式由 破折号 -一系列正值。每个值提供了笔划的交替“开”和“关”部分的长度。这个 抵消 指定到图案中笔画开始的偏移量。

每个“on”段将应用caps，就像该段是单独的子路径一样。尤其是，使用“on”长度0.0和 cairo.LineCap.ROUND 或 cairo.LineCap.SQUARE 为了沿路径分布点或正方形。

注：长度值以用户空间单位表示，在冲程时进行评估。这不一定与用户空间在 set_dash() .

如果破折号为0，则禁用破折号。

如果破折号为1，则假设对称图案具有由中的单个值指定的大小的交替开/关部分。 破折号 .

set_fill_rule(fill_rule: FillRule) → None

参数:

fill_rule -- 在开罗上下文中设置的填充规则。填充规则用于确定复杂（可能自相交）路径内部或外部的区域。当前填充规则同时影响 fill() 和 clip() .

默认填充规则为 cairo.FillRule.WINDING .

set_font_face(font_face: FontFace | None) → None

参数:

font_face -- 一 FontFace 或无以还原为默认值 FontFace

替换当前 FontFace 对象中 Context 具有 font_face .

set_font_matrix(matrix: Matrix) → None

参数:

matrix -- 一 Matrix 描述要应用于当前字体的转换。

将当前字体矩阵设置为 矩阵 . 字体矩阵将字体的设计空间（在这个空间中，em平方是1个单位乘以1个单位）转换为用户空间。通常使用一个简单的比例（参见 set_font_size() ，但可以使用更复杂的字体矩阵剪切字体或沿两个轴不相等地拉伸它。

set_font_options(options: FontOptions) → None

参数:

options -- FontOptions 使用

为设置一组自定义字体呈现选项 Context . 渲染选项是通过将这些选项与从基础曲面派生的选项合并而派生的；如果 选项 有一个默认值（如 cairo.Antialias.DEFAULT ，然后使用来自曲面的值。

set_font_size(size: float) → None

参数:

size -- 以用户空间单位表示的新字体大小

将当前字体矩阵的比例设置为 size ，替换先前设置的任何字体矩阵 set_font_size() 或 set_font_matrix() . 这将导致字体大小为 size 用户空间单位。（更准确地说，此矩阵将导致字体的em平方为 size 通过 size 在用户空间中是方形的。）

如果在不调用的情况下绘制文本 set_font_size() （或） set_font_matrix() 也不 set_scaled_font() ）的默认字体大小为10.0。

set_hairline(set_hairline: bool) → None

参数:

set_hairline -- 是否设置发际线模式

将开罗上下文中的线条设置为细线。细线在逻辑上是以当前上下文中可能的最细可渲染宽度绘制的零宽度线。在具有本机发际线支持的曲面上，将使用本机发际线功能。支持细线的曲面包括：

• PDF/PS：编码为0-宽线。

• Win32_打印：使用PS_化妆品笔渲染。

• Svg：编码为1px非缩放笔划。

• 脚本：用SET-HIRLINE函数编码。

即使对笔划宽度应用了各向异性缩放，cairo也将始终以1个设备单位宽度渲染细线。在野外，这种情况的处理并不是很明确。一些PDF、PS和SVG渲染器与cairo的输出匹配，但一些非常流行的实现(Acrobat、Chrome、rsvg)会不均匀地缩放发际线。因此，最佳做法是在调用之前重置所有各向异性缩放 stroke() 。有关示例，请参阅https://cairographics.org/cookbook/ellipses/。

在 1.23 版本加入: 仅适用于开罗1.17.6+

set_line_cap(line_cap: LineCap) → None

参数:

line_cap -- 线帽样式

设置当前线帽样式 Context .

与其他笔划参数一样，当前线帽样式由检查 stroke() 和 stroke_extents() ，但在路径构建过程中不起任何作用。

默认的线帽样式为 cairo.LineCap.BUTT .

set_line_join(line_join: LineJoin) → None

参数:

line_join -- 线条连接样式

在中设置当前线条连接样式 Context .

与其他笔划参数一样，当前的线条连接样式由 stroke() 和 stroke_extents() ，但在路径构建过程中不起任何作用。

默认的线条连接样式为 cairo.LineJoin.MITER .

set_line_width(width: float) → None

参数:

width -- 线条宽度

设置当前行宽 Context . 线条宽度值指定在用户空间中为圆形的笔的直径（尽管由于CTM的缩放/剪切/旋转，设备空间笔通常可以是椭圆）。

注：当上述描述涉及用户空间和CTM时，指的是选通操作时有效的用户空间和CTM，而不是呼叫时有效的用户空间和CTM。 set_line_width() . 最简单的用法是使这两个空间相同。也就是说，如果在呼叫 set_line_width() 以及stroking操作，然后就可以将用户空间值传递给 set_line_width() 忽略这个注释。

与其他笔划参数一样，当前线条宽度由 stroke() 和 stroke_extents() ，但在路径构建过程中不起任何作用。

默认的线条宽度值为2.0。

set_matrix(matrix: Matrix) → None

参数:

matrix -- 转变 Matrix 从用户空间到设备空间。

通过将当前转换矩阵（CTM）设置为 矩阵 .

set_miter_limit(limit: float) → None

参数:

limit -- 要设置的斜接限制

设置当前斜接限制 Context .

如果当前线条连接样式设置为 cairo.LineJoin.MITER （见 set_line_join() ）斜接限制用于确定线条是否应使用斜接而不是斜接进行连接。开罗用线条宽度划分斜接的长度。如果结果大于斜接限制，样式将转换为斜角。

与其他笔划参数一样，通过检查当前行斜接限制 stroke() 和 stroke_extents() ，但在路径构建过程中不起任何作用。

默认斜接限制值为10.0，它将内部角度小于11度的连接转换为斜接而不是斜接。作为参考，斜接限制2.0使斜接切割在60度，斜接限制1.414使切割在90度。

所需角度的斜接限制可计算为：

miter limit = 1/math.sin(angle/2)

set_operator(op: Operator) → None

参数:

op -- 要设置为在所有绘图操作中使用的合成运算符。

默认运算符为 cairo.Operator.OVER .

set_scaled_font(scaled_font: ScaledFont) → None

参数:

scaled_font -- 一 ScaledFont

替换中的当前字体、字体矩阵和字体选项 Context 和那些 ScaledFont . 除了一些翻译，目前的CTM Context 应该和 ScaledFont ，可以使用 ScaledFont.get_ctm() .

在 1.2 版本加入.

set_source(source: Pattern) → None

参数:

source -- 一 Pattern 用作后续绘图操作的源。

在中设置源模式 Context 到 来源 . 在设置新的源模式之前，此模式将用于任何后续的绘图操作。

注意：模式的转换矩阵将被锁定到用户空间，在 set_source() . 这意味着对当前转换矩阵的进一步修改不会影响源模式。见 Pattern.set_matrix() .

默认的源模式是不透明黑色的实心模式（即，它相当于 set_source_rgb(0.0, 0.0, 0.0) .

set_source_rgb(red: float, green: float, blue: float) → None

参数:

• red -- 红色成分

• green -- 颜色的绿色成分

• blue -- 颜色的蓝色成分

在中设置源模式 Context 变成不透明的颜色。在设置新的源图案之前，此不透明颜色将用于任何后续绘图操作。

颜色组件是0到1范围内的浮点数。如果传入的值超出该范围，则会将其钳制。

默认的源模式是不透明的黑色，（也就是说，它相当于 set_source_rgb(0.0, 0.0, 0.0) .

set_source_rgba(red: float, green: float, blue: float, alpha: float = 1.0) → None

参数:

• red -- 红色成分

• green -- 颜色的绿色成分

• blue -- 颜色的蓝色成分

• alpha -- 颜色的alpha分量

在中设置源模式 Context 变成半透明的颜色。在设置新的源图案之前，此颜色将用于任何后续绘图操作。

颜色和alpha组件是0到1范围内的浮点数。如果传入的值超出该范围，则会将其钳制。

默认的源模式是不透明的黑色，（也就是说，它相当于 set_source_rgba(0.0, 0.0, 0.0, 1.0) .

set_source_surface(surface: Surface, x: float = 0.0, y: float = 0.0) → None

参数:

• surface -- 一 Surface 用于设置源模式

• x -- 曲面原点的用户空间x坐标

• y -- 曲面原点的用户空间Y坐标

这是一个方便的函数，用于从 Surface 并将其设置为 Context 具有 set_source() .

这个 x 和 y 参数给出了用户空间坐标，曲面原点应在该坐标处显示。（在应用任何转换之前，曲面原点是其左上角。） x 和 y 模式被求反，然后在模式矩阵中设置为转换值。

除上述的初始转换模式矩阵外，所有其他模式属性（例如其扩展模式）都设置为默认值，如中所述。 SurfacePattern . 结果模式可以用 get_source() 以便在需要时修改这些属性（例如，创建具有 Pattern.set_extend() ）

set_tolerance(tolerance: float) → None

参数:

tolerance -- 公差，单位为设备单位（通常为像素）

设置将路径转换为梯形时使用的公差。路径的曲线段将被细分，直到原始路径和多边形近似值之间的最大偏差小于 容忍 . 默认值为0.1。值越大，性能越好，值越小，外观越好。（从默认值0.1中减少该值不太可能显著改善外观。）开罗内路径的精度受其内部算法的精度和规定的 容忍 限制为最小的可表示内部值。

show_glyphs(glyphs: Sequence[Glyph]) → None

参数:

glyphs -- 要作为序列显示的标志符号 Glyph

根据当前字体、字体大小（字体矩阵）和字体选项呈现的字形数组生成形状的绘图运算符。

show_page() → None

为支持多页的后端发出并清除当前页。使用 copy_page() 如果不想清除页面。

这是一个简单调用 ctx.get_target() . show_page()

show_text(text: str) → None

参数:

text -- 文本

根据当前字体、字体大小（字体矩阵）和字体选项呈现的文本字符串生成形状的绘图运算符。

此函数首先为文本字符串计算一组glyph。第一个标志符号的位置使其原点位于当前点。每个后续glyph的原点与前一个glyph的原点之间的偏移量为前一个glyph的高级值。

在这个调用之后，当前点被移动到下一个标志符号将被放置在同一进程中的原点。也就是说，当前点将位于最后一个glyph的原点，由其高级值偏移。这样就可以方便地显示单个逻辑字符串，并可以多次调用 show_text() .

注：该 show_text() 函数调用是cairo设计人员称之为“toy”文本API的一部分。它便于进行简短的演示和简单的程序，但不适合使用严肃文本的应用程序。见 show_glyphs() 对于开罗的“真实”文本显示API。

show_text_glyphs(utf8: str, glyphs: List[Glyph], clusters: List[TextCluster], cluster_flags: TextClusterFlags) → None

参数:

• utf8 -- 一串文本

• glyphs -- 要显示的字形列表

• clusters -- 集群映射信息列表

• cluster_flags -- 群集映射标志

抛出:

Error --

在 1.15 版本加入.

此操作的渲染效果类似于 Context.show_glyphs() 但是，如果目标曲面支持它，则使用提供的文本和集群映射来嵌入输出中所示标志符号的文本。如果目标不支持扩展属性，则此函数的作用类似于 Context.show_glyphs() 好像它已经通过了 glyphs .

utf8和glyph之间的映射由集群列表提供。每个集群包含大量的文本字节和glyph，而相邻集群覆盖相邻的utf8和glyph区域。集群应该整体覆盖utf8和glyph。

第一个集群总是覆盖从utf8开始的字节。如果 cluster_flags 没有 TextClusterFlags.BACKWARD 设置后，第一个簇还覆盖glyph的开头，否则它将覆盖glyph数组的结尾，后面的簇将向后移动。

见 TextCluster 对于有效群集的约束。

stroke() → None

根据当前线条宽度、线条连接、线条帽和短划线设置绘制当前路径的绘图运算符。后 stroke() ，当前路径将从cairo上下文中清除。见 set_line_width() ， set_line_join() ， set_line_cap() ， set_dash() 和 stroke_preserve() .

注：退化段和子路径经过特殊处理，并提供了一个有用的结果。这可能导致两种不同的情况：

1。零长度“开”段设置在 set_dash() . 如果瓶盖样式为 cairo.LineCap.ROUND 或 cairo.LineCap.SQUARE 然后将这些线段分别画成圆点或正方形。如果是 cairo.LineCap.SQUARE ，方块的方向由基础路径的方向确定。

2。由创建的子路径 move_to() 后面跟着一个 close_path() 或者打一个或多个电话给 line_to() 与 move_to() . 如果瓶盖样式为 cairo.LineCap.ROUND 然后将这些子路径绘制为圆点。注意，在 cairo.LineCap.SQUARE 一个退化的子路径将不会被绘制，（因为正确的方向是不确定的）。

在任何情况下 cairo.LineCap.BUTT 导致在退化段或子路径的情况下绘制任何内容。

stroke_extents() → Tuple[float, float, float, float]

返回:

（x1，y1，x2，y2），全浮式

• x1 ：结果范围的左侧

• y1 ：结果范围的顶部

• x2 ：结果范围的右侧

• y2 ：结果范围的底部

在用户坐标中计算一个边界框，该边界框覆盖了受 stroke() 给定当前路径和行程参数的操作。如果当前路径为空，则返回一个空矩形（0、0、0、0）。不考虑表面尺寸和剪切。

请注意，如果线条宽度设置为零，则 stroke_extents() 将返回一个空矩形。与…形成对比 path_extents() 它可以用来计算当线条宽度接近零时的非空边界。

注意 stroke_extents() 必须做更多的工作来根据笔划参数计算精确的墨迹区域，所以 path_extents() 如果需要非墨水路径扩展，则可能更适合于性能。

见 stroke() ， set_line_width() ， set_line_join() ， set_line_cap() ， set_dash() 和 stroke_preserve() .

stroke_preserve() → None

根据当前线条宽度、线条连接、线条帽和短划线设置绘制当前路径的绘图运算符。不像 stroke() ， stroke_preserve() 在cairo上下文中保留路径。

见 set_line_width() ， set_line_join() ， set_line_cap() ， set_dash() 和 stroke_preserve() .

tag_begin(tag_name: str, attributes: str) → None

参数:

• tag_name -- 标签名称

• attributes -- 标记属性

标记标记名称结构的开头。呼叫 tag_end() 使用相同的标记名来标记结构的结尾。

属性字符串的格式为“key1=value2 key2=value2…”。值可以是布尔值（真/假或1/0）、整数、浮点、字符串或数组。

字符串值用单引号（“）括起来。字符串中的单引号和反斜杠应该用反斜杠转义。

布尔值只能通过指定键设置为true。例如，属性字符串“key”等价于“key=true”。

数组括在' []'. eg "rect=[1.2 4.3 2.0 3.0] “。

如果不需要属性，则属性可以是空字符串。

见 Tags and Links Description 用于标记和属性列表。

标记嵌套无效或属性无效将导致上下文关闭，状态为 Status.TAG_ERROR .

见 tag_end() .

在 1.18.0 版本加入: 仅适用于开罗1.15.10+

tag_end(tag_name: str) → None

参数:

tag_name -- 标签名称

标记标记名称结构的结尾。

无效的标记嵌套将导致上下文关闭，状态为 Status.TAG_ERROR .

见 tag_begin() .

在 1.18.0 版本加入: 仅适用于开罗1.15.10+

text_extents(text: str) → TextExtents

参数:

text -- 获取范围的文本

获取文本字符串的范围。范围描述了一个用户空间矩形，该矩形包含文本的“墨迹”部分（如 Context.show_text() ）此外，x撊advance和y撊advance值指示当前点的提前量。 Context.show_text() .

请注意，空白字符不会直接影响矩形的大小（extents.width和extents.height）。它们确实通过改变非空白字符的位置间接地作出贡献。特别是，尾随空格字符可能不会影响矩形的大小，尽管它们会影响x_advance和y_advance值。

text_path(text: str) → None

参数:

text -- 文本

将文本的闭合路径添加到当前路径。生成的路径如果被填充，将达到类似于 Context.show_text() .

文本转换和定位类似于 Context.show_text() .

喜欢 Context.show_text() ，在此调用之后，当前点移动到下一个标志符号将放置在此同一进程中的原点。也就是说，当前点将位于最后一个glyph的原点，由其高级值偏移。这允许将多个调用链接到 Context.text_path() 不必在两者之间设置当前点。

注：该 text_path() 函数调用是cairo设计人员称之为“toy”文本API的一部分。它便于进行简短的演示和简单的程序，但不适合使用严肃文本的应用程序。见 Context.glyph_path() 对于开罗的“real”文本路径API。

transform(matrix: Matrix) → None

参数:

matrix -- 转变 Matrix 应用于用户空间轴

通过应用 矩阵 作为一个额外的转变。用户空间的新转换发生在任何现有转换之后。

translate(tx: float, ty: float) → None

参数:

• tx -- X方向的平移量

• ty -- Y方向的平移量

通过以下方式转换用户空间原点来修改当前转换矩阵（CTM） （德克萨斯州，纽约州） . 根据新调用前的CTM，此偏移量被解释为用户空间坐标。 translate() . 换句话说，用户空间原点的转换发生在任何现有的转换之后。

user_to_device(x: float, y: float) → Tuple[float, float]

参数:

• x -- 坐标X值

• y -- 坐标Y值

返回:

（x，y），两个浮动

• x ：x坐标值

• y ：坐标Y值

通过将给定点乘以当前转换矩阵（CTM），将坐标从用户空间转换为设备空间。

user_to_device_distance(dx: float, dy: float) → Tuple[float, float]

参数:

• dx -- 距离向量的x值

• dy -- 距离向量的y值

返回:

（dx，dy），两个浮球

• dx ：距离矢量的x值

• dy ：距离矢量的Y值

将距离向量从用户空间转换为设备空间。此功能类似于 Context.user_to_device() 但在转换时将忽略CTM的翻译组件 （Dx，Dy） .