Cairo Context

class Context()

Context 是你使用cairo绘制时主要用到的对象。当你要使用cairo绘制时，你首先创建一个 Context 上下文，设置目标surface及上下文的选项，调用 Context.move_to() 等方法 创建shape形状，然后调用 Context.stroke() 或者 Context.fill() 将形状绘制到surface。

Contexts 可以通过 Context.save() 保存到栈上，然后你就可以安全的修改上下文而不用担心丢失任何状态了。 完成之后调用 Context.restore() 来恢复之前保存的状态。

class cairo.Context(target)

参数:target – 上下文的目标 Surface 返回:一个新分配的上下文 Raises:没有内存时产生 MemoryError 异常

创建一个新的 Context ，所有的状态参数设置为默认值，并以 target 作为目地surface，目的surface应该使用 后端特定的函数来构建，比如： ImageSurface （或者其他的cairo后端surface的构造函数）

append_path(path)

参数:path – Path to be appended

将 path 添加到当前的路径path。 path 可以是由 Context.copy_path() 或者 Context.copy_path_flat() 返回，也可能是手动构建的（使用C语言）。

arc(xc, yc, radius, angle1, angle2)

参数:

• xc (float) – 圆心的X坐标
• yc (float) – 圆心的Y坐标
• radius (float) – 圆的半径
• angle1 (float) – 起始角度，以弧度表示
• angle2 (float) – 结束角度，以弧度表示

以给定的半径 radius 在当前的path路径上添加一个圆弧。圆弧以(xc, yc)为圆心，以 angle1 角度为起始点， 按照角度增加的方向直到 angle2 结束，如果 angle2 小于 angle1 ，则会绘制整个的圆（角度增长 2*PI 直到大于 angle1 ）。

如果有一个当前的点，那么一条从当前点到圆弧起点的线段会添加到路径。 如果你不想绘制这条线段，可以在调用 Context.arc() 之前先调用 Context.new_sub_path() 。

角度以弧度为单位。角度0是X轴的正方向（user space），角度PI/2.0（90度）是Y轴的正方向（user space），角度从 X轴方向到Y轴正方向的方向增长，因此在默认的转换矩阵（default transformation matrix）下角度以顺时针方向增长。

要从角度转换到弧度，使用 degrees * (math.pi / 180) 。

本函数以角度正向增长的方向绘制圆弧，如果需要向相反的方向绘制请参考： Context.arc_negative() 。

圆弧的绘制在user space是圆形的。要想绘制椭圆，你可以在X和Y方向以不同的数量缩放（scale）当前的转换矩阵（current transformation matrix）。 例如要绘制 *x, y, width, height 大小的椭圆，可以使用如下的代码:

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, yc, radius, angle1, angle2)

参数:

• xc (float) – 圆弧圆心X坐标
• yc (float) – 圆弧圆心Y坐标
• radius (float) – 圆弧的半径
• angle1 (float) – 圆弧的起始角度
• angle2 (float) – 圆弧的结束角度

以给定的半径 radius 在当前的path路径上添加一个圆弧。圆弧以(xc, yc)为圆心，以 angle1 角度为起始点， 按照角度减小的方向直到 angle2 结束，如果 angle2 大于 angle1 ，则会绘制整个的圆（角度减小 2*PI 直到小于 angle1 ）。

详细信息参考 Context.arc() 。这两个函数唯一的不同在于两个角度间圆弧的方向。

clip()

使用当前的path路径建立一个新的裁切区域，旧的裁切区域会根据当前的 FILL RULE （参考 Context.set_fill_rule() ） 调用 Context.fill() 填充。

调用 clip() 后当前的路径path会从 Context 清除。

裁切区域会影响所有的绘制操作——掩盖掉所有在当前绘制区域之外的改变。

调用 clip() 只能创建更小的裁切区域，无法创建更大大的裁切区域。 但是当前裁切区域也是绘制状态（graphics state）的一部分，因此通过 clip() 创建临时的裁切区域前后，你可能需要调用 Context.save()/Context.restore() 。 其他的增加裁切区域的方法只有 Context.reset_clip() 。

clip_extents()

返回:(x1, y1, x2, y2) 返回类型:(float, float, float, float)

• x1: 返回范围的左边界
• y1: 返回范围的顶部边界
• x2: 返回范围的右边界
• y2: 返回范围的底部边界

计算覆盖当前裁切区域的一个边界范围的坐标。

1.4 新版功能.

clip_preserve()

使用当前的path路径建立一个新的裁切区域，旧的裁切区域会根据当前的 FILL RULE （参考 Context.set_fill_rule() ） 调用 Context.fill() 填充。

与 Context.clip() 不同， clip_preserve() 会保存 Context 的当前路径path。

裁切区域会影响所有的绘制操作——掩盖掉所有在当前绘制区域之外的改变。

调用 clip_preserve() 只能创建更小的裁切区域，无法创建更大大的裁切区域。 但是当前裁切区域也是绘制状态（graphics state）的一部分，因此通过 clip() 创建临时的裁切区域前后，你可能需要调用 Context.save()/Context.restore() 。 其他的增加裁切区域的方法只有 Context.reset_clip() 。

close_path()

从当前点（最近调用 Context.move_to() 传递的点）到当前子路径的起点添加一条线段， 闭合当前的子路径。调用完成之后，连接到的子路径的断点成为新的当前点。

在一次绘制stroke时， close_path() 的行为与以等价的终点坐标调用 Context.line_to() 并不相同。 闭合的子路径在一次绘制stroke时， 在子路径的终点并没有’盖’（cap）（译注：见 cairo.LINE_CAP ）， 而是使用线段连接line join（译注：见 cairo.LINE_CAP ）将子路径 的起点和终点连接起来。

如果在调用 close_path() 时没有当前绘制点（current point），调用将没有任何效果。

Note: 1.2.4版本的cairo在任何调用 close_path() 时在路径闭合后都会执行 MOVE_TO， （例子参考 Context.copy_path() ）。这在某些情况下可以简化路径的处理——因为这样在处理时 就不用保存最后移动到的点了，因为 MOVE_TO 会提供这个点。

copy_clip_rectangle_list()

返回:当前裁切区域的矩形坐标列表 返回类型:四个浮点数的元组的列表

(列表中的 status 可能是 %CAIRO_STATUS_CLIP_NOT_REPRESENTABLE ，意指裁切区域不能用一个用户态矩形（user-space rectangles）代表。 status 也可能是指代其他错误的值。——pycairo中未实现）

1.4 新版功能.

copy_page()

对于支持多页操作的后端，发射（emits，疑应翻译为显示？）当前页，但是内容并不会被清除，因此当前页的内容会保留给下一个页。 如果你想在发射后得到一个空的页，需要调用 Context.show_page() 。

本函数是一个便捷函数，只是调用了 Context 的目标设备的 Surface.copy_page() 函数。

copy_path()

返回:Path Raises:没有内存时触发 MemoryError 异常

创建当前路径的一个拷贝并且以 Path 返回给用户。

copy_path_flat()

返回:Path Raises:没有内存时触发 MemoryError 异常

获取当前路径的一个 flattened 的拷贝并且以 Path 返回给用户。

本函数与 Context.copy_path() 类似，但是路径中所有的曲线都以分段线性的方式被线性化 （使用当前的容错值，current tolerance value）。即结果肯定不含有CAIRO_PATH_CURVE_TO类型的元素， 所有这种类型的元素都被替换为一系列的CAIRO_PATH_LINE_TO元素了。

curve_to(x1, y1, x2, y2, x3, y3)

:param x1:第一个控制点的X坐标 :type x1: float :param y1: 第一个控制点的Y坐标 :type y1: float :param x2: 第二个控制点的X坐标 :type x2: float :param y2: 第二个控制点的Y坐标 :type y2: float :param x3: 第三个控制点的X坐标 :type x3: float :param y3: 第三个控制点的Y坐标 :type y3: float

从当前点到 (x3, y3) 点添加一条贝塞尔曲线（cubic Bézier spline），使用 (x1, y1) 和 (x2, y2) 作为控制点。坐标均未用户态的值，调用完成之后当前点移动到 (x3, y3) 。

如果在调用 curve_to() 当前点没有被设置，函数的行为类似于调用 ctx.move_to(x1, y1) 函数。

device_to_user(x, y)

参数:

• x (float) – 坐标的X值
• y (float) – 坐标的Y值

返回:

(x, y)

返回类型:

(float, float)

通过将给定点乘以前转换矩阵（current transformation matrix，CTM）的逆矩阵将设备空间的坐标转换为用户空间的坐标。

device_to_user_distance(dx, dy)

参数:

• dx (float) – 距离向量的X值
• dy (float) – 距离向量的Y值

返回:

(dx, dy)

返回类型:

(float, float)

将设备空间的距离向量转换到用户空间。 本函数与 Context.device_to_user() 类似，但是CTM的逆矩阵的转换相关部分（translation components）会被忽略。

fill()

根据当前的填充规则（FILL RULE）填充当前路径的一个绘制操作，在绘制前，所有的子路径都被隐式的闭合了。 在调用 fill() 之后，当前的路径会从 class:Context 清除。请参考 Context.set_fill_rule() 和 Context.fill_preserve() 。

fill_extents()

返回:(x1, y1, x2, y2) 返回类型:(float, float, float, float)

• x1: 返回填充延展区域的左边界
• y1: 返回填充延展区域的上边界
• x2: 返回填充延展区域的右边界
• y2: 返回填充延展区域的下边界

计算当前路径的 Context.fill() 操作会影响（即填充）的区域的边界盒子的用户空间坐标。 如果当前路径为空，则返回一个空的矩形(0,0,0,0)，surface区域和裁切并未考虑在内（Surface dimensions and）。

与 Context.path_extents() 的区别是 Context.path_extents() 对于没有填充区域的一些路径（例如一条简单的线段）返回 非零的扩展区域。

请注意 fill_extents() 函数需要做更多的操作才能计算出精确的填充操作被填充的的区域的大小， 因此对于性能要求比较高的地方 Context.path_extents() 可能更适合。

参考 Context.fill() ， Context.set_fill_rule() 和 Context.fill_preserve().

fill_preserve()

根据当前的填充规则（FILL RULE）填充当前路径的一个绘制操作，在绘制前，所有的子路径都被隐式的闭合了。 但是不像 Context.fill() ，fill_preserve() 会保留 Context 的路径。

参考 Context.set_fill_rule() and Context.fill().

font_extents()

返回:(ascent, descent, height, max_x_advance, max_y_advance) 返回类型:(float, float, float, float, float)

获取当前选择字体的延展区域（extents）。

get_antialias()

返回:当前的 ANTIALIAS 模式（由 Context.set_antialias() 设置）。

get_current_point()

返回:(x, y) 返回类型:(float, float)

• 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.stroke_to_path().

以下函数会修改当前点但是并不改变当前的路径： Context.show_text().

以下函数会删除（unset）当前的路径，因此也会删除单签点： Context.fill(), Context.stroke().

get_dash()

返回:(dashes, offset) 返回类型:(tuple, float)

• dashes: dash数组
• offset: 当前dash的偏移值。

获取当前的dash数组。

1.4 新版功能.

get_dash_count()

返回:dash数组的长度，如果dash数组没有被设置则返回0。 返回类型:int

参考 Context.set_dash() 和 Context.get_dash().

1.4 新版功能.

get_fill_rule()

返回:当前的 FILL RULE （由 Context.set_fill_rule() 函数设置）。

get_font_face()

返回:Context 当前的 FontFace 。

get_font_matrix()

返回:Context 当前的 Matrix 。

参考 Context.set_font_matrix().

get_font_options()

返回:Context 当前的 FontOptions 。

获取 Context.set_font_options() 设置的字体渲染选项。 注意返回的选项并不包含从底层surface继承的选项；从字面意思来看返回的就是 传递给 Context.set_font_options() 的选项。

get_group_target()

返回:the target Surface.

返回 Context 的当前目的 Surface ，或者是传递给 Context 的 原来的目的，或者是最近调用 Context.push_group() 或者 Context.push_group_with_content() 设置的当前组的目的surface。

1.2 新版功能.

get_line_cap()

返回:当前的 LINE_CAP 风格，由 Context.set_line_cap() 设置。

get_line_join()

返回:当前的 LINE_JOIN 风格，由 Context.set_line_join() 设置。

get_line_width()

返回:当前的线宽 返回类型:float

本函数返回由 Context.set_line_width() 设置的当前的线宽。 注意即使CTM在调用 Context.set_line_width() 之后已经被改变，返回的值也不变。

get_matrix()

返回:当前转换矩阵 Matrix (CTM)

get_miter_limit()

返回:当前的斜切限制，由 Context.set_miter_limit() 设置。 返回类型:float

get_operator()

返回:Context 的当前合成操作 OPERATOR 。

get_scaled_font()

返回:Context 当前的 ScaledFont 。

1.4 新版功能.

get_source()

返回:Context 的当前pattern源 Pattern 。

get_target()

返回:Context 的目的surface Surface 。

get_tolerance()

返回:当前的容错值（the current tolerance value），由 Context.set_tolerance() 设置。 返回类型:float

glyph_extents(glyphs[, num_glyphs])

参数:

• glyphs (a sequence of (int, float, float)) – glyphs
• num_glyphs (int) – number of glyphs to measure, defaults to using all

返回:

x_bearing, y_bearing, width, height, x_advance, y_advance

返回类型:

6-tuple of float

Gets the extents for an array of glyphs. The extents describe a user-space rectangle that encloses the “inked” portion of the glyphs, (as they would be drawn by Context.show_glyphs()). Additionally, the x_advance and y_advance values indicate the amount by which the current point would be advanced by Context.show_glyphs().

Note that whitespace glyphs do not contribute to the size of the rectangle (extents.width and extents.height).

glyph_path(glyphs[, num_glyphs])

参数:

• glyphs (a sequence of (int, float, float)) – glyphs to show
• num_glyphs (int) – number of glyphs to show, defaults to showing all

Adds closed paths for the glyphs to the current path. The generated path if filled, achieves an effect similar to that of Context.show_glyphs().

has_current_point()

returns: True iff a current point is defined on the current path.

See Context.get_current_point() for details on the current point.

1.6 新版功能.

identity_matrix()

Resets the current transformation Matrix (CTM) by setting it equal to the identity matrix. That is, the user-space and device-space axes will be aligned and one user-space unit will transform to one device-space unit.

in_fill(x, y)

参数:

• x (float) – 测试点的X坐标
• y (float) – 测试点的Y坐标

返回:

如果该点在当前路径的 Context.fill() 操作的影响区域内返回True， surface的尺寸和裁切并没有考虑在内。

参考 Context.fill() ， Context.set_fill_rule() 和 Context.fill_preserve() 。

in_stroke(x, y)

参数:

• x (float) – X coordinate of the point to test
• y (float) – Y coordinate of the point to test

返回:

True iff the point is inside the area that would be affected by a Context.stroke() operation given the current path and stroking parameters. Surface dimensions and clipping are not taken into account.

See Context.stroke(), Context.set_line_width(), Context.set_line_join(), Context.set_line_cap(), Context.set_dash(), and Context.stroke_preserve().

line_to(x, y)

参数:

• x (float) – the X coordinate of the end of the new line
• y (float) – the Y coordinate of the end of the new line

Adds a line to the path from the current point to position (x, y) in user-space coordinates. After this call the current point will be (x, y).

If there is no current point before the call to line_to() this function will behave as ctx.move_to(x, y).

mask(pattern)

参数:pattern – a Pattern

A drawing operator that paints the current source using the alpha channel of pattern as a mask. (Opaque areas of pattern are painted with the source, transparent areas are not painted.)

mask_surface(surface, x=0.0, y=0.0)

参数:

• surface – a Surface
• x (float) – X coordinate at which to place the origin of surface
• y (float) – Y coordinate at which to place the origin of surface

A drawing operator that paints the current source using the alpha channel of surface as a mask. (Opaque areas of surface are painted with the source, transparent areas are not painted.)

move_to(x, y)

参数:

• x (float) – the X coordinate of the new position
• y (float) – the Y coordinate of the new position

Begin a new sub-path. After this call the current point will be (x, y).

new_path()

Clears the current path. After this call there will be no path and no current point.

new_sub_path()

Begin a new sub-path. Note that the existing path is not affected. After this call there will be no current point.

In many cases, this call is not needed since new sub-paths are frequently started with Context.move_to().

A call to new_sub_path() is particularly useful when beginning a new sub-path with one of the Context.arc() calls. This makes things easier as it is no longer necessary to manually compute the arc’s initial coordinates for a call to Context.move_to().

1.6 新版功能.

paint()

A drawing operator that paints the current source everywhere within the current clip region.

paint_with_alpha(alpha)

参数:alpha (float) – alpha value, between 0 (transparent) and 1 (opaque)

A drawing operator that paints the current source everywhere within the current clip region using a mask of constant alpha value alpha. The effect is similar to Context.paint(), but the drawing is faded out using the alpha value.

path_extents()

返回:(x1, y1, x2, y2) 返回类型:(float, float, float, float)

• x1: left of the resulting extents
• y1: top of the resulting extents
• x2: right of the resulting extents
• y2: bottom of the resulting extents

Computes a bounding box in user-space coordinates covering the points on the current path. If the current path is empty, returns an empty rectangle (0, 0, 0, 0). Stroke parameters, fill rule, surface dimensions and clipping are not taken into account.

Contrast with Context.fill_extents() and Context.stroke_extents() which return the extents of only the area that would be “inked” by the corresponding drawing operations.

The result of path_extents() is defined as equivalent to the limit of Context.stroke_extents() with cairo.LINE_CAP_ROUND as the line width approaches 0.0, (but never reaching the empty-rectangle returned by Context.stroke_extents() for a line width of 0.0).

Specifically, this means that zero-area sub-paths such as Context.move_to(); Context.line_to() segments, (even degenerate cases where the coordinates to both calls are identical), will be considered as contributing to the extents. However, a lone Context.move_to() will not contribute to the results of Context.path_extents().

1.6 新版功能.

pop_group()

返回:a newly created SurfacePattern containing the results of all drawing operations performed to the group.

Terminates the redirection begun by a call to Context.push_group() or Context.push_group_with_content() and returns a new pattern containing the results of all drawing operations performed to the group.

The pop_group() function calls Context.restore(), (balancing a call to Context.save() by the Context.push_group() function), so that any changes to the graphics state will not be visible outside the group.

1.2 新版功能.

pop_group_to_source()

Terminates the redirection begun by a call to Context.push_group() or Context.push_group_with_content() and installs the resulting pattern as the source Pattern in the given Context.

The behavior of this function is equivalent to the sequence of operations:

group = cairo_pop_group()
ctx.set_source(group)

but is more convenient as their is no need for a variable to store the short-lived pointer to the pattern.

The Context.pop_group() function calls Context.restore(), (balancing a call to Context.save() by the Context.push_group() function), so that any changes to the graphics state will not be visible outside the group.

1.2 新版功能.

push_group()

Temporarily redirects drawing to an intermediate surface known as a group. The redirection lasts until the group is completed by a call to Context.pop_group() or Context.pop_group_to_source(). These calls provide the result of any drawing to the group as a pattern, (either as an explicit object, or set as the source pattern).

This group functionality can be convenient for performing intermediate compositing. One common use of a group is to render objects as opaque within the group, (so that they occlude each other), and then blend the result with translucence onto the destination.

Groups can be nested arbitrarily deep by making balanced calls to Context.push_group()/Context.pop_group(). Each call pushes/pops the new target group onto/from a stack.

The push_group() function calls Context.save() so that any changes to the graphics state will not be visible outside the group, (the pop_group functions call Context.restore()).

By default the intermediate group will have a CONTENT type of cairo.CONTENT_COLOR_ALPHA. Other content types can be chosen for the group by using Context.push_group_with_content() instead.

As an example, here is how one might fill and stroke a path with translucence, but without any portion of the fill being visible under the stroke:

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 – a CONTENT indicating the type of group that will be created

Temporarily redirects drawing to an intermediate surface known as a group. The redirection lasts until the group is completed by a call to Context.pop_group() or Context.pop_group_to_source(). These calls provide the result of any drawing to the group as a pattern, (either as an explicit object, or set as the source pattern).

The group will have a content type of content. The ability to control this content type is the only distinction between this function and Context.push_group() which you should see for a more detailed description of group rendering.

1.2 新版功能.

rectangle(x, y, width, height)

参数:

• x (float) – the X coordinate of the top left corner of the rectangle
• y (float) – the Y coordinate to the top left corner of the rectangle
• width (float) – the width of the rectangle
• height (float) – the height of the rectangle

Adds a closed sub-path rectangle of the given size to the current path at position (x, y) in user-space coordinates.

This function is logically equivalent to:

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, dy1, dx2, dy2, dx3, dy4)

参数:

• dx1 (float) – the X offset to the first control point
• dy1 (float) – the Y offset to the first control point
• dx2 (float) – the X offset to the second control point
• dy2 (float) – the Y offset to the second control point
• dx3 (float) – the X offset to the end of the curve
• dy3 (float) – the Y offset to the end of the curve

Raises:

cairo.Error if called with no current point.

Relative-coordinate version of Context.curve_to(). All offsets are relative to the current point. Adds a cubic Bézier spline to the path from the current point to a point offset from the current point by (dx3, dy3), using points offset by (dx1, dy1) and (dx2, dy2) as the control points. After this call the current point will be offset by (dx3, dy3).

Given a current point of (x, y), ctx.rel_curve_to(dx1, dy1, dx2, dy2, dx3, dy3) is logically equivalent to ctx.curve_to(x+dx1, y+dy1, x+dx2, y+dy2, x+dx3, y+dy3).

rel_line_to(dx, dy)

参数:

• dx (float) – the X offset to the end of the new line
• dy (float) – the Y offset to the end of the new line

Raises:

cairo.Error if called with no current point.

Relative-coordinate version of Context.line_to(). Adds a line to the path from the current point to a point that is offset from the current point by (dx, dy) in user space. After this call the current point will be offset by (dx, dy).

Given a current point of (x, y), ctx.rel_line_to(dx, dy) is logically equivalent to ctx.line_to(x + dx, y + dy).

rel_move_to(dx, dy)

参数:

• dx (float) – the X offset
• dy (float) – the Y offset

Raises:

cairo.Error if called with no current point.

Begin a new sub-path. After this call the current point will offset by (dx, dy).

Given a current point of (x, y), ctx.rel_move_to(dx, dy) is logically equivalent to ctx.(x + dx, y + dy).

reset_clip()

Reset the current clip region to its original, unrestricted state. That is, set the clip region to an infinitely large shape containing the target surface. Equivalently, if infinity is too hard to grasp, one can imagine the clip region being reset to the exact bounds of the target surface.

Note that code meant to be reusable should not call reset_clip() as it will cause results unexpected by higher-level code which calls clip(). Consider using save() and restore() around clip() as a more robust means of temporarily restricting the clip region.

restore()

Restores Context to the state saved by a preceding call to save() and removes that state from the stack of saved states.

rotate(angle)

参数:angle (float) – angle (in radians) by which the user-space axes will be rotated

Modifies the current transformation matrix (CTM) by rotating the user-space axes by angle radians. The rotation of the axes takes places after any existing transformation of user space. The rotation direction for positive angles is from the positive X axis toward the positive Y axis.

save()

Makes a copy of the current state of Context and saves it on an internal stack of saved states. When restore() is called, Context will be restored to the saved state. Multiple calls to save() and restore() can be nested; each call to restore() restores the state from the matching paired save().

scale(sx, sy)

参数:

• sx (float) – scale factor for the X dimension
• sy (float) – scale factor for the Y dimension

Modifies the current transformation matrix (CTM) by scaling the X and Y user-space axes by sx and sy respectively. The scaling of the axes takes place after any existing transformation of user space.

select_font_face(family[, slant[, weight]])

参数:

• family (str) – a font family name
• slant – the FONT_SLANT of the font, defaults to cairo.FONT_SLANT_NORMAL.
• weight – the FONT_WEIGHT of the font, defaults to cairo.FONT_WEIGHT_NORMAL.

Note: The select_font_face() function call is part of what the cairo designers call the “toy” text API. It is convenient for short demos and simple programs, but it is not expected to be adequate for serious text-using applications.

Selects a family and style of font from a simplified description as a family name, slant and weight. Cairo provides no operation to list available family names on the system (this is a “toy”, remember), but the standard CSS2 generic family names, (“serif”, “sans-serif”, “cursive”, “fantasy”, “monospace”), are likely to work as expected.

For “real” font selection, see the font-backend-specific font_face_create functions for the font backend you are using. (For example, if you are using the freetype-based cairo-ft font backend, see cairo_ft_font_face_create_for_ft_face() or cairo_ft_font_face_create_for_pattern().) The resulting font face could then be used with cairo_scaled_font_create() and cairo_set_scaled_font().

Similarly, when using the “real” font support, you can call directly into the underlying font system, (such as fontconfig or freetype), for operations such as listing available fonts, etc.

It is expected that most applications will need to use a more comprehensive font handling and text layout library, (for example, pango), in conjunction with cairo.

If text is drawn without a call to select_font_face(), (nor set_font_face() nor set_scaled_font()), the default family is platform-specific, but is essentially “sans-serif”. Default slant is cairo.FONT_SLANT_NORMAL, and default weight is cairo.FONT_WEIGHT_NORMAL.

This function is equivalent to a call to ToyFontFace followed by set_font_face().

set_antialias(antialias)

参数:antialias – the new ANTIALIAS mode

Set the antialiasing mode of the rasterizer used for drawing shapes. This value is a hint, and a particular backend may or may not support a particular value. At the current time, no backend supports cairo.ANTIALIAS_SUBPIXEL when drawing shapes.

Note that this option does not affect text rendering, instead see FontOptions.set_antialias().

set_dash(dashes[, offset=0])

参数:

• dashes (sequence of float) – a sequence specifying alternate lengths of on and off stroke portions.
• offset (int) – an offset into the dash pattern at which the stroke should start, defaults to 0.

Raises:

cairo.Error if any value in dashes is negative, or if all values are 0.

Sets the dash pattern to be used by stroke(). A dash pattern is specified by dashes - a sequence of positive values. Each value provides the length of alternate “on” and “off” portions of the stroke. The offset specifies an offset into the pattern at which the stroke begins.

Each “on” segment will have caps applied as if the segment were a separate sub-path. In particular, it is valid to use an “on” length of 0.0 with cairo.LINE_CAP_ROUND or cairo.LINE_CAP_SQUARE in order to distributed dots or squares along a path.

Note: The length values are in user-space units as evaluated at the time of stroking. This is not necessarily the same as the user space at the time of set_dash().

If the number of dashes is 0 dashing is disabled.

If the number of dashes is 1 a symmetric pattern is assumed with alternating on and off portions of the size specified by the single value in dashes.

set_fill_rule(fill_rule)

参数:fill_rule – 要设置的 FILL RULE 。填充规则用于 决定一个区域是属于还是不属于一个复杂的路径（潜在的自相交等）。当前的填充规则会影响 fill() 和 clip() 。

默认的填充规则是 cairo.FILL_RULE_WINDING 。

set_font_face(font_face)

参数:font_face – a FontFace, or None to restore to the default FontFace

Replaces the current FontFace object in the Context with font_face.

set_font_matrix(matrix)

参数:matrix – a Matrix describing a transform to be applied to the current font.

Sets the current font matrix to matrix. The font matrix gives a transformation from the design space of the font (in this space, the em-square is 1 unit by 1 unit) to user space. Normally, a simple scale is used (see set_font_size()), but a more complex font matrix can be used to shear the font or stretch it unequally along the two axes

set_font_options(options)

参数:options – FontOptions to use

Sets a set of custom font rendering options for the Context. Rendering options are derived by merging these options with the options derived from underlying surface; if the value in options has a default value (like cairo.ANTIALIAS_DEFAULT), then the value from the surface is used.

set_font_size(size)

参数:size (float) – the new font size, in user space units

Sets the current font matrix to a scale by a factor of size, replacing any font matrix previously set with set_font_size() or set_font_matrix(). This results in a font size of size user space units. (More precisely, this matrix will result in the font’s em-square being a size by size square in user space.)

If text is drawn without a call to set_font_size(), (nor set_font_matrix() nor set_scaled_font()), the default font size is 10.0.

set_line_cap(line_cap)

参数:line_cap – a LINE_CAP style

Sets the current line cap style within the Context.

As with the other stroke parameters, the current line cap style is examined by stroke(), stroke_extents(), and stroke_to_path(), but does not have any effect during path construction.

The default line cap style is cairo.LINE_CAP_BUTT.

set_line_join(line_join)

参数:line_join – a LINE_JOIN style

Sets the current line join style within the Context.

As with the other stroke parameters, the current line join style is examined by stroke(), stroke_extents(), and stroke_to_path(), but does not have any effect during path construction.

The default line join style is cairo.LINE_JOIN_MITER.

set_line_width(width)

参数:width (float) – a line width

Sets the current line width within the Context. The line width value specifies the diameter of a pen that is circular in user space, (though device-space pen may be an ellipse in general due to scaling/shear/rotation of the CTM).

Note: When the description above refers to user space and CTM it refers to the user space and CTM in effect at the time of the stroking operation, not the user space and CTM in effect at the time of the call to set_line_width(). The simplest usage makes both of these spaces identical. That is, if there is no change to the CTM between a call to set_line_width() and the stroking operation, then one can just pass user-space values to set_line_width() and ignore this note.

As with the other stroke parameters, the current line width is examined by stroke(), stroke_extents(), and stroke_to_path(), but does not have any effect during path construction.

The default line width value is 2.0.

set_matrix(matrix)

参数:matrix – a transformation Matrix from user space to device space.

Modifies the current transformation matrix (CTM) by setting it equal to matrix.

set_miter_limit(limit)

参数:limit – miter limit to set

Sets the current miter limit within the Context.

If the current line join style is set to cairo.LINE_JOIN_MITER (see set_line_join()), the miter limit is used to determine whether the lines should be joined with a bevel instead of a miter. Cairo divides the length of the miter by the line width. If the result is greater than the miter limit, the style is converted to a bevel.

As with the other stroke parameters, the current line miter limit is examined by stroke(), stroke_extents(), and stroke_to_path(), but does not have any effect during path construction.

The default miter limit value is 10.0, which will convert joins with interior angles less than 11 degrees to bevels instead of miters. For reference, a miter limit of 2.0 makes the miter cutoff at 60 degrees, and a miter limit of 1.414 makes the cutoff at 90 degrees.

A miter limit for a desired angle can be computed as:

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

set_operator(op)

参数:op – the compositing OPERATOR to set for use in all drawing operations.

The default operator is cairo.OPERATOR_OVER.

set_scaled_font(scaled_font)

参数:scaled_font – a ScaledFont

Replaces the current font face, font matrix, and font options in the Context with those of the ScaledFont. Except for some translation, the current CTM of the Context should be the same as that of the ScaledFont, which can be accessed using ScaledFont.get_ctm().

1.2 新版功能.

set_source(source)

参数:source – a Pattern to be used as the source for subsequent drawing operations.

Sets the source pattern within Context to source. This pattern will then be used for any subsequent drawing operation until a new source pattern is set.

Note: The pattern’s transformation matrix will be locked to the user space in effect at the time of set_source(). This means that further modifications of the current transformation matrix will not affect the source pattern. See Pattern.set_matrix().

The default source pattern is a solid pattern that is opaque black, (that is, it is equivalent to set_source_rgb(0.0, 0.0, 0.0).

set_source_rgb(red, green, blue)

参数:

• red (float) – red component of color
• green (float) – green component of color
• blue (float) – blue component of color

Sets the source pattern within Context to an opaque color. This opaque color will then be used for any subsequent drawing operation until a new source pattern is set.

The color components are floating point numbers in the range 0 to 1. If the values passed in are outside that range, they will be clamped.

The default source pattern is opaque black, (that is, it is equivalent to set_source_rgb(0.0, 0.0, 0.0).

set_source_rgba(red, green, blue[, alpha=1.0])

参数:

• red (float) – red component of color
• green (float) – green component of color
• blue (float) – blue component of color
• alpha (float) – alpha component of color

Sets the source pattern within Context to a translucent color. This color will then be used for any subsequent drawing operation until a new source pattern is set.

The color and alpha components are floating point numbers in the range 0 to 1. If the values passed in are outside that range, they will be clamped.

The default source pattern is opaque black, (that is, it is equivalent to set_source_rgba(0.0, 0.0, 0.0, 1.0).

set_source_surface(surface[, x=0.0[, y=0.0]])

参数:

• surface – a Surface to be used to set the source pattern
• x (float) – User-space X coordinate for surface origin
• y (float) – User-space Y coordinate for surface origin

This is a convenience function for creating a pattern from a Surface and setting it as the source in Context with set_source().

The x and y parameters give the user-space coordinate at which the surface origin should appear. (The surface origin is its upper-left corner before any transformation has been applied.) The x and y patterns are negated and then set as translation values in the pattern matrix.

Other than the initial translation pattern matrix, as described above, all other pattern attributes, (such as its extend mode), are set to the default values as in SurfacePattern. The resulting pattern can be queried with get_source() so that these attributes can be modified if desired, (eg. to create a repeating pattern with Pattern.set_extend()).

set_tolerance(tolerance)

参数:tolerance (float) – the tolerance, in device units (typically pixels)

Sets the tolerance used when converting paths into trapezoids. Curved segments of the path will be subdivided until the maximum deviation between the original path and the polygonal approximation is less than tolerance. The default value is 0.1. A larger value will give better performance, a smaller value, better appearance. (Reducing the value from the default value of 0.1 is unlikely to improve appearance significantly.) The accuracy of paths within Cairo is limited by the precision of its internal arithmetic, and the prescribed tolerance is restricted to the smallest representable internal value.

show_glyphs(glyphs[, num_glyphs])

参数:

• glyphs (a sequence of (int, float, float)) – glyphs to show
• num_glyphs (int) – number of glyphs to show, defaults to showing all glyphs

A drawing operator that generates the shape from an array of glyphs, rendered according to the current font face, font size (font matrix), and font options.

show_page()

Emits and clears the current page for backends that support multiple pages. Use copy_page() if you don’t want to clear the page.

This is a convenience function that simply calls ctx.get_target() . show_page()

show_text(text)

参数:text (str) – text

A drawing operator that generates the shape from a string of text, rendered according to the current font_face, font_size (font_matrix), and font_options.

This function first computes a set of glyphs for the string of text. The first glyph is placed so that its origin is at the current point. The origin of each subsequent glyph is offset from that of the previous glyph by the advance values of the previous glyph.

After this call the current point is moved to the origin of where the next glyph would be placed in this same progression. That is, the current point will be at the origin of the final glyph offset by its advance values. This allows for easy display of a single logical string with multiple calls to show_text().

Note: The show_text() function call is part of what the cairo designers call the “toy” text API. It is convenient for short demos and simple programs, but it is not expected to be adequate for serious text-using applications. See show_glyphs() for the “real” text display API in cairo.

stroke()

A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings. After stroke(), the current path will be cleared from the cairo context. See set_line_width(), set_line_join(), set_line_cap(), set_dash(), and stroke_preserve().

Note: Degenerate segments and sub-paths are treated specially and provide a useful result. These can result in two different situations:

1. Zero-length “on” segments set in set_dash(). If the cap style is cairo.LINE_CAP_ROUND or cairo.LINE_CAP_SQUARE then these segments will be drawn as circular dots or squares respectively. In the case of cairo.LINE_CAP_SQUARE, the orientation of the squares is determined by the direction of the underlying path.

2. A sub-path created by move_to() followed by either a close_path() or one or more calls to line_to() to the same coordinate as the move_to(). If the cap style is cairo.LINE_CAP_ROUND then these sub-paths will be drawn as circular dots. Note that in the case of cairo.LINE_CAP_SQUARE a degenerate sub-path will not be drawn at all, (since the correct orientation is indeterminate).

In no case will a cap style of cairo.LINE_CAP_BUTT cause anything to be drawn in the case of either degenerate segments or sub-paths.

stroke_extents()

返回:(x1, y1, x2, y2) 返回类型:(float, float, float, float)

• x1: left of the resulting extents
• y1: top of the resulting extents
• x2: right of the resulting extents
• y2: bottom of the resulting extents

Computes a bounding box in user coordinates covering the area that would be affected, (the “inked” area), by a stroke() operation given the current path and stroke parameters. If the current path is empty, returns an empty rectangle (0, 0, 0, 0). Surface dimensions and clipping are not taken into account.

Note that if the line width is set to exactly zero, then stroke_extents() will return an empty rectangle. Contrast with path_extents() which can be used to compute the non-empty bounds as the line width approaches zero.

Note that stroke_extents() must necessarily do more work to compute the precise inked areas in light of the stroke parameters, so path_extents() may be more desirable for sake of performance if non-inked path extents are desired.

See stroke(), set_line_width(), set_line_join(), set_line_cap(), set_dash(), and stroke_preserve().

stroke_preserve()

A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings. Unlike stroke(), stroke_preserve() preserves the path within the cairo context.

See set_line_width(), set_line_join(), set_line_cap(), set_dash(), and stroke_preserve().

text_extents(text)

参数:text (str) – text to get extents for 返回:x_bearing, y_bearing, width, height, x_advance, y_advance 返回类型:6-tuple of float

Gets the extents for a string of text. The extents describe a user-space rectangle that encloses the “inked” portion of the text, (as it would be drawn by Context.show_text()). Additionally, the x_advance and y_advance values indicate the amount by which the current point would be advanced by Context.show_text().

Note that whitespace characters do not directly contribute to the size of the rectangle (extents.width and extents.height). They do contribute indirectly by changing the position of non-whitespace characters. In particular, trailing whitespace characters are likely to not affect the size of the rectangle, though they will affect the x_advance and y_advance values.

text_path(text)

参数:text (str) – text

Adds closed paths for text to the current path. The generated path if filled, achieves an effect similar to that of Context.show_text().

Text conversion and positioning is done similar to Context.show_text().

Like Context.show_text(), After this call the current point is moved to the origin of where the next glyph would be placed in this same progression. That is, the current point will be at the origin of the final glyph offset by its advance values. This allows for chaining multiple calls to to Context.text_path() without having to set current point in between.

Note: The text_path() function call is part of what the cairo designers call the “toy” text API. It is convenient for short demos and simple programs, but it is not expected to be adequate for serious text-using applications. See Context.glyph_path() for the “real” text path API in cairo.

transform(matrix)

参数:matrix – a transformation Matrix to be applied to the user-space axes

Modifies the current transformation matrix (CTM) by applying matrix as an additional transformation. The new transformation of user space takes place after any existing transformation.

translate(tx, ty)

参数:

• tx (float) – amount to translate in the X direction
• ty (float) – amount to translate in the Y direction

Modifies the current transformation matrix (CTM) by translating the user-space origin by (tx, ty). This offset is interpreted as a user-space coordinate according to the CTM in place before the new call to translate(). In other words, the translation of the user-space origin takes place after any existing transformation.

user_to_device(x, y)

参数:

• x (float) – X value of coordinate
• y (float) – Y value of coordinate

返回:

(x, y)

返回类型:

(float, float)

• x: X value of coordinate
• y: Y value of coordinate

Transform a coordinate from user space to device space by multiplying the given point by the current transformation matrix (CTM).

user_to_device_distance(dx, dy)

参数:

• dx (float) – X value of a distance vector
• dy (float) – Y value of a distance vector

返回:

(dx, dy)

返回类型:

(float, float)

• dx: X value of a distance vector
• dy: Y value of a distance vector

Transform a distance vector from user space to device space. This function is similar to Context.user_to_device() except that the translation components of the CTM will be ignored when transforming (dx,dy).