[cairo-commit] pycairo/doc/reference context.rst, NONE, 1.1 exceptions.rst, NONE, 1.1 index.rst, NONE, 1.1 matrix.rst, NONE, 1.1 mattributes.rst, NONE, 1.1 paths.rst, NONE, 1.1 patterns.rst, NONE, 1.1 surfaces.rst, NONE, 1.1 text.rst, NONE, 1.1
Steve Chaplin
commit at pdx.freedesktop.org
Tue Dec 9 22:57:49 PST 2008
- Previous message: [cairo-commit] pycairo/doc c-api.rst, NONE, 1.1 conf.py, NONE, 1.1 faq.rst, NONE, 1.1 index.rst, NONE, 1.1 Makefile.am, 1.2, 1.3 overview.rst, NONE, 1.1 README, NONE, 1.1
- Next message: [cairo-commit] pycairo ChangeLog,1.282,1.283
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]
Committed by: stevech1097
Update of /cvs/cairo/pycairo/doc/reference
In directory kemper:/tmp/cvs-serv27440/doc/reference
Added Files:
context.rst exceptions.rst index.rst matrix.rst
mattributes.rst paths.rst patterns.rst surfaces.rst text.rst
Log Message:
'SC'
--- NEW FILE: context.rst ---
.. _context:
*******************************
Cairo Context (incomplete docs)
*******************************
.. comment block
example reST:
(add back '..' for each line except ':' lines)
. class:: module.C[(signature)]
.. method:: C.method(p1, p2)
:param p1: xxx
:param p2: xxx
:type p2: integer or None
:returns: xxx
:rtype: list of strings
:raises: xxx
staticmethod:: name(signature)
attribute:: C.name
..
class Context()
===============
.. class:: Context()
.. method:: append_path()
.. method:: arc()
.. method:: arc_negative()
.. method:: clip()
.. method:: clip_extents()
.. method:: clip_preserve()
.. method:: close_path()
.. method:: copy_clip_rectangle_list()
.. method:: copy_page()
.. method:: copy_path()
.. method:: copy_path_flat()
.. method:: curve_to()
.. method:: device_to_user()
.. method:: device_to_user_distance()
.. method:: fill()
.. method:: fill_extents()
.. method:: fill_preserve()
.. method:: font_extents()
.. method:: get_antialias()
.. method:: get_current_point()
.. method:: get_dash()
.. method:: get_dash_count()
.. method:: get_fill_rule()
.. method:: get_font_face()
.. method:: get_font_matrix()
.. method:: get_font_options()
.. method:: get_group_target()
.. method:: get_line_cap()
.. method:: get_line_join()
.. method:: get_line_width()
.. method:: get_matrix()
.. method:: get_miter_limit()
.. method:: get_operator()
.. method:: get_scaled_font()
.. method:: get_source()
.. method:: get_target()
.. method:: get_tolerance()
.. method:: glyph_extents()
.. method:: glyph_path()
.. method:: has_current_point()
.. method:: identity_matrix()
.. method:: in_fill()
.. method:: in_stroke()
.. method:: line_to()
.. method:: mask()
.. method:: mask_surface()
.. method:: move_to()
.. method:: new_path()
.. method:: new_sub_path()
.. method:: paint()
.. method:: paint_with_alpha()
.. method:: path_extents()
.. method:: pop_group()
.. method:: pop_group_to_source()
.. method:: push_group()
.. method:: push_group_with_content()
.. method:: rectangle()
.. method:: rel_curve_to()
.. method:: rel_line_to()
.. method:: rel_move_to()
.. method:: reset_clip()
.. method:: restore()
.. method:: rotate()
.. method:: save()
.. method:: scale()
.. method:: select_font_face()
.. method:: set_antialias()
.. method:: set_dash()
.. method:: set_fill_rule()
.. method:: set_font_face()
.. method:: set_font_matrix()
.. method:: set_font_options()
.. method:: set_font_size()
.. method:: set_line_cap()
.. method:: set_line_join()
.. method:: set_line_width()
.. method:: set_matrix()
.. method:: set_miter_limit()
.. method:: set_operator()
.. method:: set_source()
.. method:: set_source_rgb()
.. method:: set_source_rgba()
.. method:: set_source_surface()
.. method:: set_tolerance()
.. method:: show_glyphs()
.. method:: show_page()
.. method:: show_text()
.. method:: stroke()
.. method:: stroke_extents()
.. method:: stroke_preserve()
.. method:: text_extents()
.. method:: text_path()
.. method:: transform()
.. method:: translate()
.. method:: user_to_device()
.. method:: user_to_device_distance()
.. comment
incorporate these notes:
C : cr = cairo_create (surface);
Py: ctx = cairo.Context (surface)
C : cairo_set_dash (cairo_t *cr, double *dashes, int ndash, double offset);
Py: ctx.set_dash (dash_sequence, offset)
Methods supporting default argument values:
ctx.mask_surface (surface, x=0.0, y=0.0)
ctx.select_font_face (family, slant=cairo.FONT_SLANT_NORMAL)
weight=cairo.FONT_WEIGHT_NORMAL)
ctx.set_source_surface (surface, x=0.0, y=0.0)
ctx.set_source_rgba (r, g, b, a=1.0)
--- NEW FILE: exceptions.rst ---
.. _exceptions:
**********
Exceptions
**********
When a cairo function or method call fails an exception is raised. I/O errors
raise IOError, memory errors raise MemoryError, and all other errors raise
cairo.Error.
cairo.Error()
=============
.. exception:: cairo.Error
This exception is raised when a cairo object returns an error status.
--- NEW FILE: index.rst ---
.. _reference_index:
***************************
Reference (unfinished docs)
***************************
.. toctree::
:maxdepth: 2
exceptions
mattributes
context
matrix
paths
patterns
surfaces
text
--- NEW FILE: matrix.rst ---
.. _matrix:
******
Matrix
******
class Matrix()
==============
*Matrix* is used throughout cairo to convert between different coordinate
spaces. A *Matrix* holds an affine transformation, such as a scale, rotation,
shear, or a combination of these. The transformation of a point (x,y) is
given by::
x_new = xx * x + xy * y + x0
y_new = yx * x + yy * y + y0
The current transformation matrix of a :class:`Context`, represented as a
*Matrix*, defines the transformation from user-space coordinates to device-space
coordinates.
Some standard Python operators can be used with matrices:
To read the values from a *Matrix*::
xx, yx, xy, yy, x0, y0 = matrix
To multiply two matrices::
matrix3 = matrix1 * matrix2
To compare two matrices::
matrix1 == matrix2
matrix1 != matrix2
For more information on matrix transformation see http://www.cairographics.org/matrix_transform
.. class:: Matrix(xx = 1.0, yx = 0.0, xy = 0.0, yy = 1.0, x0 = 0.0, y0 = 0.0)
:param xx: xx component of the affine transformation
:type xx: float
:param yx: yx component of the affine transformation
:type yx: float
:param xy: xy component of the affine transformation
:type xy: float
:param yy: yy component of the affine transformation
:type yy: float
:param x0: X translation component of the affine transformation
:type x0: float
:param y0: Y translation component of the affine transformation
:type y0: float
Create a new *Matrix* with the affine transformation given by *xx, yx, xy,
yy, x0, y0*. The transformation is given by::
x_new = xx * x + xy * y + x0
y_new = yx * x + yy * y + y0
To create a new identity matrix::
matrix = cairo.Matrix()
To create a matrix with a transformation which translates by tx and ty in the X and Y dimensions, respectively::
matrix = cairo.Matrix(x0=tx, y0=ty)
To create a matrix with a transformation that scales by sx and sy in the X and Y dimensions, respectively::
matrix = cairo.Matrix(xx=sy, yy=sy)
.. method:: init_rotate(radians)
:param radians: angle of rotation, in radians. The direction of rotation
is defined such that positive angles rotate in the direction from the
positive X axis toward the positive Y axis. With the default axis
orientation of cairo, positive angles rotate in a clockwise direction.
:type radians: float
:returns: a new *Matrix*
This is a classmethod which creates a new *Matrix* set to a
transformation that rotates by *radians*.
.. method:: invert()
:returns: If *Matrix* has an inverse, modifies *Matrix* to be the
inverse matrix and returns *None*
:raises: :class:`cairo.Error` if the *Matrix* as no inverse
Changes *Matrix* to be the inverse of it's original value. Not all
transformation matrices have inverses; if the matrix collapses points
together (it is *degenerate*), then it has no inverse and this function
will fail.
.. method:: rotate(radians)
:param radians: angle of rotation, in radians. The direction of rotation
is defined such that positive angles rotate in the direction from the
positive X axis toward the positive Y axis. With the default axis
orientation of cairo, positive angles rotate in a clockwise direction.
:type radians: float
Initialize *Matrix* to a transformation that rotates by *radians*.
.. method:: scale(sx, sy)
:param sx: scale factor in the X direction
:type sx: float
:param sy: scale factor in the Y direction
:type sy: float
Applies scaling by *sx, sy* to the transformation in *Matrix*. The
effect of the new transformation is to first scale the coordinates by
*sx* and *sy*, then apply the original transformation to the
coordinates.
.. method:: transform_distance(dx, dy)
:param dx: X component of a distance vector.
:type dx: float
:param dy: Y component of a distance vector.
:type dy: float
:returns: the transformed distance vector (dx,dy)
:rtype: 2-tuple of float
Transforms the distance vector *(dx,dy)* by *Matrix*. This is similar to
:meth:`.transform_point` except that the translation components of the
transformation are ignored. The calculation of the returned vector is as
follows::
dx2 = dx1 * a + dy1 * c
dy2 = dx1 * b + dy1 * d
Affine transformations are position invariant, so the same vector always
transforms to the same vector. If *(x1,y1)* transforms to *(x2,y2)* then
*(x1+dx1,y1+dy1)* will transform to *(x1+dx2,y1+dy2)* for all values
of *x1* and *x2*.
.. method:: transform_point(x, y)
:param x: X position.
:type x: float
:param y: Y position.
:type y: float
:returns: the transformed point (x,y)
:rtype: 2-tuple of float
Transforms the point *(x, y)* by *Matrix*.
.. method:: translate(tx, ty)
:param tx: amount to translate in the X direction
:type tx: float
:param ty: amount to translate in the Y direction
:type ty: float
Applies a transformation by *tx, ty* to the transformation in
*Matrix*. The effect of the new transformation is to first translate the
coordinates by *tx* and *ty*, then apply the original transformation to the
coordinates.
--- NEW FILE: mattributes.rst ---
.. _mattributes:
*******************************
Module Functions and Attributes
*******************************
Module Functions
================
.. function:: cairo.cairo_version()
:returns: the encoded version
:rtype: int
Returns the version of the underlying C cairo library, encoded in a single
integer.
.. function:: cairo.cairo_version_string()
:returns: the encoded version
:rtype: str
Returns the version of the underlying C cairo library as a human-readable
string of the form "X.Y.Z".
Module Attributes
=================
.. attribute:: cairo.version
the pycairo version, as a string
.. attribute:: cairo.version_info
the pycairo version, as a tuple
.. attribute:: cairo.HAS_ATSUI_FONT
cairo.HAS_FT_FONT
cairo.HAS_GLITZ_SURFACE
cairo.HAS_IMAGE_SURFACE
cairo.HAS_HAS_PDF_SURFACE
cairo.HAS_PNG_FUNCTIONS
cairo.HAS_PS_SURFACE
cairo.HAS_SVG_SURFACE
cairo.HAS_USER_FONT
cairo.HAS_QUARTZ_SURFACE
cairo.HAS_WIN32_FONT
cairo.HAS_WIN32_SURFACE
cairo.HAS_XCB_SURFACE
cairo.HAS_XLIB_SURFACE
1 if the feature is present in the underlying C cairo library,
0 otherwise
.. _mattributes_antialias:
.. attribute:: cairo.ANTIALIAS_DEFAULT
cairo.ANTIALIAS_NONE
cairo.ANTIALIAS_GRAY
cairo.ANTIALIAS_SUBPIXEL
* *cairo.ANTIALIAS_DEFAULT*: Use the default antialiasing for the subsystem and target device
* *cairo.ANTIALIAS_NONE*: Use a bilevel alpha mask
* *cairo.ANTIALIAS_GRAY*: Perform single-color antialiasing (using shades of gray for black text on a white background, for example).
* *cairo.ANTIALIAS_SUBPIXEL*: Perform antialiasing by taking advantage of the order of subpixel elements on devices such as LCD panels
ANTIALIAS_x Specifies the type of antialiasing to do when rendering text or shapes.
.. _mattributes_content:
.. attribute:: cairo.CONTENT_COLOR
cairo.CONTENT_ALPHA
cairo.CONTENT_COLOR_ALPHA
* *cairo.CONTENT_COLOR*: The surface will hold color content only.
* *cairo.CONTENT_ALPHA*: The surface will hold alpha content only.
* *cairo.CONTENT_COLOR_ALPHA*: The surface will hold color and alpha content.
These attributes are used to describe the content that a surface will
contain, whether color information, alpha information (translucence
vs. opacity), or both.
.. _mattributes_extend:
.. attribute:: cairo.EXTEND_NONE
cairo.EXTEND_REPEAT
cairo.EXTEND_REFLECT
cairo.EXTEND_PAD
* *cairo.EXTEND_NONE*: pixels outside of the source pattern are fully transparent
* *cairo.EXTEND_REPEAT*: the pattern is tiled by repeating
* *cairo.EXTEND_REFLECT*: the pattern is tiled by reflecting at the edges (Implemented for surface patterns since 1.6)
* *cairo.EXTEND_PAD*: pixels outside of the pattern copy the closest pixel from the source (Since 1.2; but only implemented for surface patterns since 1.6)
These attributes are used to describe how pattern color/alpha will be
determined for areas "outside" the pattern's natural area, (for example,
outside the surface bounds or outside the gradient geometry).
The default extend mode is *cairo.EXTEND_NONE* for surface patterns and *cairo.EXTEND_PAD* for gradient patterns.
New entries may be added in future versions.
.. attribute:: cairo.FILL_RULE_WINDING
cairo.FILL_RULE_EVEN_ODD
* *cairo.FILL_RULE_WINDING*: If the path crosses the ray from left-to-right, counts +1. If the path crosses the ray from right to left, counts -1. (Left and right are determined from the perspective of looking along the ray from the starting point.) If the total count is non-zero, the point will be filled.
* *cairo.FILL_RULE_EVEN_ODD*: Counts the total number of intersections, without regard to the orientation of the contour. If the total number of intersections is odd, the point will be filled.
These attributes are used to select how paths are filled. For both fill
rules, whether or not a point is included in the fill is determined by taking
a ray from that point to infinity and looking at intersections with the
path. The ray can be in any direction, as long as it doesn't pass through the
end point of a segment or have a tricky intersection such as intersecting
tangent to the path. (Note that filling is not actually implemented in this
way. This is just a description of the rule that is applied.)
The default fill rule is *cairo.FILL_RULE_WINDING*.
New entries may be added in future versions.
.. _mattributes_filter:
.. attribute:: cairo.FILTER_FAST
cairo.FILTER_GOOD
cairo.FILTER_BEST
cairo.FILTER_NEAREST
cairo.FILTER_BILINEAR
cairo.FILTER_GAUSSIAN
* *cairo.FILTER_FAST*: A high-performance filter, with quality similar *cairo.FILTER_NEAREST*
* *cairo.FILTER_GOOD*: A reasonable-performance filter, with quality similar to *cairo.FILTER_BILINEAR*
* *cairo.FILTER_BEST*: The highest-quality available, performance may not be suitable for interactive use.
* *cairo.FILTER_NEAREST*: Nearest-neighbor filtering
* *cairo.FILTER_BILINEAR*: Linear interpolation in two dimensions
* *cairo.FILTER_GAUSSIAN*: This filter value is currently unimplemented, and should not be used in current code.
These attributes are used to indicate what filtering should be applied when reading pixel values from patterns. See :meth:`SurfacePattern.set_filter` for indicating the desired filter to be used with a particular pattern.
.. attribute:: cairo.FONT_WEIGHT_NORMAL
cairo.FONT_WEIGHT_BOLD
* *cairo.FONT_WEIGHT_NORMAL*: Normal font weight
* *cairo.FONT_WEIGHT_BOLD*: Bold font weight
These attributes specify variants of a font face based on their weight.
.. attribute:: cairo.FONT_SLANT_NORMAL
cairo.FONT_SLANT_ITALIC
cairo.FONT_SLANT_OBLIQUE
* *cairo.FONT_SLANT_NORMAL*: Upright font style
* *cairo.FONT_SLANT_ITALIC*: Italic font style
* *cairo.FONT_SLANT_OBLIQUE*: Oblique font style
These attributes specify variants of a font face based on their slant.
.. attribute:: cairo.FORMAT_ARGB32
cairo.FORMAT_RGB24
cairo.FORMAT_A8
cairo.FORMAT_A1
cairo.FORMAT_RGB16_565
* *cairo.FORMAT_ARGB32*: each pixel is a 32-bit quantity, with alpha in the upper 8 bits, then red, then green, then blue. The 32-bit quantities are stored native-endian. Pre-multiplied alpha is used. (That is, 50% transparent red is 0x80800000, not 0x80ff0000.)
* *cairo.FORMAT_RGB24*: each pixel is a 32-bit quantity, with the upper 8 bits unused. Red, Green, and Blue are stored in the remaining 24 bits in that order.
* *cairo.FORMAT_A8*: each pixel is a 8-bit quantity holding an alpha value.
* *cairo.FORMAT_A1*: each pixel is a 1-bit quantity holding an alpha value. Pixels are packed together into 32-bit quantities. The ordering of the bits matches the endianess of the platform. On a big-endian machine, the first pixel is in the uppermost bit, on a little-endian machine the first pixel is in the least-significant bit.
* *cairo.FORMAT_RGB16_565*: This format value is deprecated. It has never been properly implemented in cairo and should not be used by applications. (since 1.2)
These attributes are used to identify the memory format of image data.
New entries may be added in future versions.
.. _mattributes_hint_metrics:
.. attribute:: cairo.HINT_METRICS_DEFAULT
cairo.HINT_METRICS_OFF
cairo.HINT_METRICS_ON
* *cairo.HINT_METRICS_DEFAULT*: Hint metrics in the default manner for the font backend and target device
* *cairo.HINT_METRICS_OFF*: Do not hint font metrics
* *cairo.HINT_METRICS_ON*: Hint font metrics
These attributes specify whether to hint font metrics; hinting font metrics means quantizing them so that they are integer values in device space. Doing this improves the consistency of letter and line spacing, however it also means that text will be laid out differently at different zoom factors.
.. _mattributes_hint_style:
.. attribute:: cairo.HINT_STYLE_DEFAULT
cairo.HINT_STYLE_NONE
cairo.HINT_STYLE_SLIGHT
cairo.HINT_STYLE_MEDIUM
cairo.HINT_STYLE_FULL
* *cairo.HINT_STYLE_DEFAULT*: Use the default hint style for font backend and target device
* *cairo.HINT_STYLE_NONE*: Do not hint outlines
* *cairo.HINT_STYLE_SLIGHT*: Hint outlines slightly to improve contrast while retaining good fidelity to the original shapes.
* *cairo.HINT_STYLE_MEDIUM*: Hint outlines with medium strength giving a compromise between fidelity to the original shapes and contrast
* *cairo.HINT_STYLE_FULL*: Hint outlines to maximize contrast
These attributes specify the type of hinting to do on font outlines. Hinting is the process of fitting outlines to the pixel grid in order to improve the appearance of the result. Since hinting outlines involves distorting them, it also reduces the faithfulness to the original outline shapes. Not all of the outline hinting styles are supported by all font backends.
New entries may be added in future versions.
.. attribute:: cairo.LINE_CAP_BUTT
cairo.LINE_CAP_ROUND
cairo.LINE_CAP_SQUARE
* *cairo.LINE_CAP_BUTT*: start(stop) the line exactly at the start(end) point
* *cairo.LINE_CAP_ROUND*: use a round ending, the center of the circle is the end point
* *cairo.LINE_CAP_SQUARE*: use squared ending, the center of the square is the end point
These attributes specify how to render the endpoints of the path when stroking.
The default line cap style is *cairo.LINE_CAP_BUTT*
.. attribute:: cairo.LINE_JOIN_MITER
cairo.LINE_JOIN_ROUND
cairo.LINE_JOIN_BEVEL
* *cairo.LINE_JOIN_MITER*: use a sharp (angled) corner, see :meth:`Context.set_miter_limit`
* *cairo.LINE_JOIN_ROUND*: use a rounded join, the center of the circle is the joint point
* *cairo.LINE_JOIN_BEVEL*: use a cut-off join, the join is cut off at half the line width from the joint point
These attributes specify how to render the junction of two lines when stroking.
The default line join style is *cairo.LINE_JOIN_MITER*
.. attribute:: cairo.OPERATOR_CLEAR
cairo.OPERATOR_SOURCE
cairo.OPERATOR_OVER
cairo.OPERATOR_IN
cairo.OPERATOR_OUT
cairo.OPERATOR_ATOP
cairo.OPERATOR_DEST
cairo.OPERATOR_DEST_OVER
cairo.OPERATOR_DEST_IN
cairo.OPERATOR_DEST_OUT
cairo.OPERATOR_DEST_ATOP
cairo.OPERATOR_XOR
cairo.OPERATOR_ADD
cairo.OPERATOR_SATURATE
* *cairo.OPERATOR_CLEAR*: clear destination layer (bounded)
* *cairo.OPERATOR_SOURCE*: replace destination layer (bounded)
* *cairo.OPERATOR_OVER*: draw source layer on top of destination layer (bounded)
* *cairo.OPERATOR_IN*: draw source where there was destination content (unbounded)
* *cairo.OPERATOR_OUT*: draw source where there was no destination content (unbounded)
* *cairo.OPERATOR_ATOP*: draw source on top of destination content and only there
* *cairo.OPERATOR_DEST*: ignore the source
* *cairo.OPERATOR_DEST_OVER*: draw destination on top of source
* *cairo.OPERATOR_DEST_IN*: leave destination only where there was source content (unbounded)
* *cairo.OPERATOR_DEST_OUT*: leave destination only where there was no source content
* *cairo.OPERATOR_DEST_ATOP*: leave destination on top of source content and only there (unbounded)
* *cairo.OPERATOR_XOR*: source and destination are shown where there is only one of them
* *cairo.OPERATOR_ADD*: source and destination layers are accumulated
* *cairo.OPERATOR_SATURATE*: like over, but assuming source and dest are disjoint geometries
These attributes are used to set the compositing operator for all cairo
drawing operations.
The default operator is *cairo.OPERATOR_OVER*.
The operators marked as *unbounded* modify their destination even outside
of the mask layer (that is, their effect is not bound by the mask layer).
However, their effect can still be limited by way of clipping.
To keep things simple, the operator descriptions here
document the behavior for when both source and destination are either fully
transparent or fully opaque. The actual implementation works for
translucent layers too.
For a more detailed explanation of the effects of each operator, including
the mathematical definitions, see http://cairographics.org/operators.
.. attribute:: cairo.PATH_MOVE_TO
cairo.PATH_LINE_TO
cairo.PATH_CURVE_TO
cairo.PATH_CLOSE_PATH
* *cairo.PATH_MOVE_TO*: A move-to operation
* *cairo.PATH_LINE_TO*: A line-to operation
* *cairo.PATH_CURVE_TO*: A curve-to operation
* *cairo.PATH_CLOSE_PATH*: A close-path operation
These attributes are used to describe the type of one portion of a path
when represented as a :class:`Path`.
.. See #cairo_path_data_t for details.
.. attribute:: cairo.PS_LEVEL_2
cairo.PS_LEVEL_3
* *cairo.PS_LEVEL_2*: The language level 2 of the PostScript specification.
* *cairo.PS_LEVEL_3*: The language level 3 of the PostScript specification.
These attributes are used to describe the language level of the PostScript
Language Reference that a generated PostScript file will conform to. Note:
the attributes are only defined when cairo has been compiled with PS
support enabled.
.. _mattributes_subpixel:
.. attribute:: cairo.SUBPIXEL_ORDER_DEFAULT
cairo.SUBPIXEL_ORDER_RGB
cairo.SUBPIXEL_ORDER_BGR
cairo.SUBPIXEL_ORDER_VRGB
cairo.SUBPIXEL_ORDER_VBGR
* *cairo.SUBPIXEL_ORDER_DEFAULT*: Use the default subpixel order for for the target device
* *cairo.SUBPIXEL_ORDER_RGB*: Subpixel elements are arranged horizontally with red at the left
* *cairo.SUBPIXEL_ORDER_BGR*: Subpixel elements are arranged horizontally with blue at the left
* *cairo.SUBPIXEL_ORDER_VRGB*: Subpixel elements are arranged vertically with red at the top
* *cairo.SUBPIXEL_ORDER_VBGR*: Subpixel elements are arranged vertically with blue at the top
The subpixel order specifies the order of color elements within
each pixel on the display device when rendering with an
antialiasing mode of :attr:`cairo.ANTIALIAS_SUBPIXEL`.
--- NEW FILE: paths.rst ---
.. _paths:
*****
Paths
*****
class Path()
============
*Path* cannot be instantiated directly, it is created by calling
:meth:`Context.copy_path` and :meth:`Context.copy_path_flat`.
Path is an iterator, see examples/warpedtext.py for example usage.
str(path) lists the path elements.
--- NEW FILE: patterns.rst ---
.. _patterns:
********
Patterns
********
Patterns are the paint with which cairo draws. The primary use of patterns is
as the source for all cairo drawing operations, although they can also be used
as masks, that is, as the brush too.
A cairo *Pattern* is created by using one of the *PatternType* constructors
listed below, or implicitly through *Context.set_source_<type>()* methods.
class Pattern()
===============
*Pattern* is the abstract base class from which all the other pattern classes
derive. It cannot be instantiated directly.
.. class:: Pattern()
.. method:: get_matrix()
:returns: a new :class:`Matrix` which stores a copy of the *Pattern's* transformation matrix
.. method:: set_matrix(matrix)
:param matrix: a cairo matrix (:class:`Matrix`)
Sets the *Pattern's* transformation matrix to *matrix*. This matrix is a
transformation from user space to pattern space.
When a *Pattern* is first created it always has the identity matrix for
its transformation matrix, which means that pattern space is initially
identical to user space.
Important: Please note that the direction of this transformation matrix
is from user space to pattern space. This means that if you imagine the
flow from a *Pattern* to user space (and on to device space), then
coordinates in that flow will be transformed by the inverse of the
*Pattern* matrix.
For example, if you want to make a *Pattern* appear twice as large as it
does by default the correct code to use is::
matrix = cairo.Matrix(xx=0.5,yy=0.5)
pattern.set_matrix(matrix)
Meanwhile, using values of 2.0 rather than 0.5 in the code above would
cause the *Pattern* to appear at half of its default size.
Also, please note the discussion of the user-space locking semantics of
:class:`Context.set_source`.
class SolidPattern(:class:`Pattern`)
====================================
.. class:: SolidPattern(red, green, blue, alpha=1.0)
:param red: red component of the color
:type red: float
:param green: green component of the color
:type green: float
:param blue: blue component of the color
:type blue: float
:param alpha: alpha component of the color
:type alpha: float
:returns: a new *SolidPattern*
:raises: *MemoryError* in case of no memory
Creates a new *SolidPattern* corresponding to a translucent color. 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.
.. method:: get_rgba()
:returns: (red, green, blue, alpha) a tuple of float
Gets the solid color for a *SolidPattern*.
Since: 1.4
class SurfacePattern(:class:`Pattern`)
======================================
.. class:: SurfacePattern(surface)
:param surface: a cairo :class:`Surface`
:returns: the newly created *SurfacePattern*
:raises: MemoryError in case of no memory.
Create a new *SurfacePattern* for the given surface.
.. method:: get_extend()
:returns: the current extend strategy used for drawing the *Pattern*.
:rtype: int
Gets the current extend mode for the *Pattern*. See
:ref:`EXTEND attributes <mattributes_extend>`
for details on the semantics of each extend strategy.
.. method:: get_filter()
:returns: the current filter used for resizing the *Pattern*.
:rtype: int
Gets the current filter for the *Pattern*. See
:ref:`FILTER attributes <mattributes_filter>`
for details on each filter.
.. method:: get_surface()
:returns: the :class:`Surface` of the *SurfacePattern*.
Since: 1.4
.. method:: set_extend(extend)
:param extend: an extend describing how the area outside of the *Pattern* will be drawn
Sets the mode to be used for drawing outside the area of a *Pattern*. See
:ref:`EXTEND attributes <mattributes_extend>`
for details on the semantics of each extend strategy.
The default extend mode is :attr:`cairo.EXTEND_NONE` for *SurfacePatterns*
and :attr:`cairo.EXTEND_PAD` for *Gradient* patterns.
.. method:: set_filter(filter)
:param filter: a filter describing the filter to use for resizing the *Pattern*
Sets the filter to be used for resizing when using this pattern. See
:ref:`FILTER attributes <mattributes_filter>`
for details on each filter.
Note that you might want to control filtering even when you do not have
an explicit *Pattern* object, (for example when using
:meth:`Context.set_source_surface`). In these cases, it is convenient to use
:meth:`Context.get_source` to get access to the pattern that cairo creates
implicitly. For example::
context.set_source_surface(image, x, y)
surfacepattern.set_filter(context.get_source(), cairo.FILTER_NEAREST)
class Gradient(:class:`Pattern`)
================================
*Gradient* is an abstract base class from which other *Pattern* classes
derive. It cannot be instantiated directly.
.. class:: Gradient()
.. method:: add_color_stop_rgb(offset, red, green, blue)
:param offset: an offset in the range [0.0 .. 1.0]
:type offset: float
:param red: red component of color
:type red: float
:param green: green component of color
:type green: float
:param blue: blue component of color
:type blue: float
Adds an opaque color stop to a *Gradient* pattern. The offset specifies
the location along the gradient's control vector. For example, a
*LinearGradient's* control vector is from (x0,y0) to (x1,y1) while a
*RadialGradient's* control vector is from any point on the start circle
to the corresponding point on the end circle.
The color is specified in the same way as in :meth:`Context.set_source_rgb`.
If two (or more) stops are specified with identical offset values, they
will be sorted according to the order in which the stops are added,
(stops added earlier will compare less than stops added later). This can
be useful for reliably making sharp color transitions instead of the
typical blend.
.. method:: add_color_stop_rgba(offset, red, green, blue, alpha)
:param offset: an offset in the range [0.0 .. 1.0]
:type offset: float
:param red: red component of color
:type red: float
:param green: green component of color
:type green: float
:param blue: blue component of color
:type blue: float
:param alpha: alpha component of color
:type alpha: float
Adds an opaque color stop to a *Gradient* pattern. The offset specifies
the location along the gradient's control vector. For example, a
*LinearGradient's* control vector is from (x0,y0) to (x1,y1) while a
*RadialGradient's* control vector is from any point on the start circle
to the corresponding point on the end circle.
The color is specified in the same way as in :meth:`Context.set_source_rgb`.
If two (or more) stops are specified with identical offset values, they
will be sorted according to the order in which the stops are added,
(stops added earlier will compare less than stops added later). This can
be useful for reliably making sharp color transitions instead of the
typical blend.
class LinearGradient(:class:`Gradient`)
=======================================
.. class:: LinearGradient(x0, y0, x1, y1)
:param x0: x coordinate of the start point
:type x0: float
:param y0: y coordinate of the start point
:type y0: float
:param x1: x coordinate of the end point
:type x1: float
:param y1: y coordinate of the end point
:type y1: float
:returns: a new *LinearGradient*
:raises: *MemoryError* in case of no memory
Create a new *LinearGradient* along the line defined by (x0, y0) and (x1,
y1). Before using the *Gradient* pattern, a number of color stops should
be defined using :meth:`Gradient.add_color_stop_rgb` or
:meth:`Gradient.add_color_stop_rgba`
Note: The coordinates here are in pattern space. For a new *Pattern*,
pattern space is identical to user space, but the relationship between the
spaces can be changed with :meth:`Pattern.set_matrix`
.. method:: get_linear_points()
:returns: (x0, y0, x1, y1) - a tuple of float
* x0: return value for the x coordinate of the first point
* y0: return value for the y coordinate of the first point
* x1: return value for the x coordinate of the second point
* y1: return value for the y coordinate of the second point
Gets the gradient endpoints for a *LinearGradient*.
Since: 1.4
class RadialGradient(:class:`Gradient`)
=======================================
.. class:: RadialGradient(cx0, cy0, radius0, cx1, cy1, radius1)
:param cx0: x coordinate for the center of the start circle
:type cx0: float
:param cy0: y coordinate for the center of the start circle
:type cy0: float
:param radius0: radius of the start circle
:type radius0: float
:param cx1: x coordinate for the center of the end circle
:type cx1: float
:param cy1: y coordinate for the center of the end circle
:type cy1: float
:param radius1: radius of the end circle
:type radius1: float
:returns: the newly created *RadialGradient*
:raises: *MemoryError* in case of no memory
Creates a new *RadialGradient* pattern between the two circles defined by
(cx0, cy0, radius0) and (cx1, cy1, radius1). Before using the gradient
pattern, a number of color stops should be defined using
:meth:`Gradient.add_color_stop_rgb` or :meth:`Gradient.add_color_stop_rgba`.
Note: The coordinates here are in pattern space. For a new pattern, pattern
space is identical to user space, but the relationship between the spaces
can be changed with :meth:`Pattern.set_matrix`.
.. method:: get_radial_circles()
:returns: (x0, y0, r0, x1, y1, r1) - a tuple of float
* x0: return value for the x coordinate of the center of the first circle
* y0: return value for the y coordinate of the center of the first circle
* r0: return value for the radius of the first circle
* x1: return value for the x coordinate of the center of the second circle
* y1: return value for the y coordinate of the center of the second circle
* r1: return value for the radius of the second circle
Gets the *Gradient* endpoint circles for a *RadialGradient*, each
specified as a center coordinate and a radius.
Since: 1.4
--- NEW FILE: surfaces.rst ---
.. _surfaces:
**************************
Surfaces (incomplete docs)
**************************
cairo.Surface is the abstract type representing all different drawing targets
that cairo can render to. The actual drawings are performed using a
:class:`cairo.Context`.
A cairo.Surface is created by using backend-specific constructors
of the form cairo.<XXX>Surface().
class Surface()
===============
.. class:: Surface()
*Surface* is the abstract base class from which all the other surface classes
derive. It cannot be instantiated directly.
.. method:: copy_page()
Emits the current page for backends that support multiple pages, but
doesn't clear it, so that the contents of the current page will be
retained for the next page. Use :meth:`.show_page` if you want to get an
empty page after the emission.
:meth:`Context.copy_page` is a convenience function for this.
Since: 1.6
.. method:: create_similar(content, width, height)
:param content: the content for the new surface
:param width: width of the new surface, (in device-space units)
:type width: int
:param height: height of the new surface (in device-space units)
:type width: int
:returns: a newly allocated *Surface*.
Create a *Surface* that is as compatible as possible with the existing
surface. For example the new surface will have the same fallback
resolution and :class:`FontOptions`. Generally, the new surface will
also use the same backend, unless that is not possible for some
reason.
See the documentation for :ref:`content <mattributes_content>`
for full details of the content options.
Initially the surface contents are all 0 (transparent if contents have
transparency, black otherwise.)
.. method:: finish()
This method finishes the *Surface* and drops all references to external
resources. For example, for the Xlib backend it means that cairo will no
longer access the drawable, which can be freed. After calling finish()
the only valid operations on a *Surface* are flushing and finishing it.
Further drawing to the surface will not affect the surface but will
instead trigger a :exc:`cairo.Error` exception.
.. method:: flush()
Do any pending drawing for the *Surface* and also restore any temporary
modification's cairo has made to the *Surface's* state. This method
must be called before switching from drawing on the *Surface* with cairo
to drawing on it directly with native APIs. If the *Surface* doesn't
support direct access, then this function does nothing.
.. method:: get_content()
:returns: The content type of *Surface*.
This function returns the content type of *Surface* which indicates
whether the surface contains color and/or alpha information. See
:ref:`content <mattributes_content>`.
Since: 1.2
.. method:: get_device_offset()
:returns: (x_offset, y_offset) a tuple of float
* x_offset: the offset in the X direction, in device units
* y_offset: the offset in the Y direction, in device units
This method returns the previous device offset set by :meth:`.set_device_offset`.
Since: 1.2
.. method:: get_fallback_resolution()
:returns: (x_pixels_per_inch, y_pixels_per_inch) a tuple of float
* x_pixels_per_inch: horizontal pixels per inch
* y_pixels_per_inch: vertical pixels per inch
This method returns the previous fallback resolution set by
:meth:`.set_fallback_resolution`, or default fallback resolution if
never set.
Since: 1.8
.. method:: get_font_options()
:returns: a :class:`FontOptions`
Retrieves the default font rendering options for the *Surface*. This
allows display surfaces to report the correct subpixel order for
rendering on them, print surfaces to disable hinting of metrics and so
forth. The result can then be used with :class:`ScaledFont`.
.. method:: mark_dirty()
Tells cairo that drawing has been done to *Surface* using means other
than cairo, and that cairo should reread any cached areas. Note that you
must call :meth:`.flush` before doing such drawing.
.. method:: mark_dirty_rectangle(x, y, width, height)
:param x: X coordinate of dirty rectangle
:type x: int
:param y: Y coordinate of dirty rectangle
:type y: int
:param width: width of dirty rectangle
:type width: int
:param height: height of dirty rectangle
:type height: int
Like :meth:`.mark_dirty`, but drawing has been done only to the
specified rectangle, so that cairo can retain cached contents for other
parts of the surface.
Any cached clip set on the *Surface* will be reset by this function, to
make sure that future cairo calls have the clip set that they expect.
.. method:: set_device_offset()
.. method:: set_fallback_resolution()
.. method:: show_page()
.. method:: write_to_png()
.. comment
C: cairo_surface_write_to_png (surface, filename);
cairo_surface_write_to_png_stream (surface, write_func, closure);
Py: surface.write_to_png (f)
where 'f' is a filename, a file object, or a file-like object (an object
that has a "write" method, for example StringIO, cStringIO)
Py: surface = cairo.PDFSurface (f, width_in_points, height_in_points)
surface = cairo.PSSurface (f, width_in_points, height_in_points)
surface = cairo.SVGSurface (f, width_in_points, height_in_points)
where 'f' is a filename, a file object, or a file-like object
class ImageSurface(:class:`Surface`)
====================================
.. class:: ImageSurface
.. comment
C : surface = cairo_image_surface_create (format, width, height);
surface = cairo_image_surface_create_from_png (filename);
surface = cairo_image_surface_create_from_png_stream (read_func, closure);
surface = cairo_image_surface_create_for_data (data, format, w, h, stride)
Py: surface = cairo.ImageSurface (format, width, height)
surface = cairo.ImageSurface.create_from_png (f)
where 'f' is a filename, a file object, or a file-like object
surface = cairo.ImageSurface.create_for_data (data, format, w, h, stride)
where 'data' if a writable Python buffer object
..
.. method:: create_for_data()
.. method:: create_from_png()
.. method:: format_stride_for_width()
.. method:: get_data()
.. method:: get_format()
.. method:: get_height()
.. method:: get_width()
.. method:: get_stride()
class PDFSurface(:class:`Surface`)
==================================
.. class:: PDFSurface
.. comment
C: surface = cairo_pdf_surface_create (filename, width_in_points,
height_in_points);
surface = cairo_ps_surface_create (filename, width_in_points,
height_in_points);
surface = cairo_svg_surface_create (filename, width_in_points,
height_in_points);
..
.. method:: set_size()
class PSSurface(:class:`Surface`)
=================================
.. class:: PSSurface
.. method:: dsc_begin_page_setup()
.. method:: dsc_begin_setup()
.. method:: dsc_comment()
.. method:: get_eps()
.. method:: ps_level_to_string()
.. method:: restrict_to_level()
.. method:: set_eps()
.. method:: set_size()
class SVGSurface(:class:`Surface`)
==================================
.. class:: SVGSurface
class Win32Surface(:class:`Surface`)
====================================
.. class:: Win32Surface
class XlibSurface(:class:`Surface`)
===================================
.. class:: XlibSurface
*XlibSurface* cannot be instantiated directly. But an XlibSurface instance
can be returned from a function call when using pygtk.
.. method:: get_depth()
.. method:: get_height()
.. method:: get_width()
--- NEW FILE: text.rst ---
.. _text:
****
Text
****
Cairo has two sets of text rendering capabilities:
* The functions with text in their name form cairo's toy text API. The toy API takes UTF-8 encoded text and is limited in its functionality to rendering simple left-to-right text with no advanced features. That means for example that most complex scripts like Hebrew, Arabic, and Indic scripts are out of question. No kerning or correct positioning of diacritical marks either. The font selection is pretty limited too and doesn't handle the case that the selected font does not cover the characters in the text. This set of functions are really that, a toy text API, for testing and demonstration purposes. Any serious application should avoid them.
* The functions with glyphs in their name form cairo's low-level text API. The low-level API relies on the user to convert text to a set of glyph indexes and positions. This is a very hard problem and is best handled by external libraries, like the pangocairo that is part of the Pango text layout and rendering library. Pango is available from http://www.pango.org/.
class FontFace()
================
A *cairo.FontFace* specifies all aspects of a font other than the size or font
matrix (a font matrix is used to distort a font by sheering it or scaling it
unequally in the two directions). A *FontFace* can be set on a
:class:`Context` by using :meth:`Context.set_font_face` the size and font
matrix are set with :meth:`Context.set_font_size` and
:meth:`Context.set_font_matrix`.
*FontFace* cannot be instantiated directly, it is returned from
:meth:`Context.get_font_face`
There are various types of *FontFace*, depending on the font backend they
use.
class ScaledFont()
==================
A *ScaledFont* is a font scaled to a particular size and device resolution. A
*ScaledFont* is most useful for low-level font usage where a library or
application wants to cache a reference to a scaled font to speed up the
computation of metrics.
There are various types of scaled fonts, depending on the font backend they
use.
.. class:: ScaledFont(font_face, font_matrix, ctm, options)
:param font_face: a :class:`FontFace` instance
:param font_matrix: font space to user space transformation :class:`Matrix` for the
font. In the simplest case of a N point font, this matrix is
just a scale by N, but it can also be used to shear the font
or stretch it unequally along the two axes. See :meth:`Context.set_font_matrix`.
:param ctm: user to device transformation :class:`Matrix` with which the font will
be used.
:param options: a :class:`FontOptions` instance to use when getting metrics for the font and rendering with it.
Creates a *ScaledFont* object from a *FontFace* and matrices that describe
the size of the font and the environment in which it will be used.
.. method:: extents()
:returns: (ascent, descent, height, max_x_advance, max_y_advance), a tuple of float values.
Gets the metrics for a *ScaledFont*.
.. method:: get_font_face()
:returns: the :class:`FontFace` that this *ScaledFont* was created for.
Since: 1.2
.. method:: get_scale_matrix()
:returns: the scale :class:`Matrix`
The scale matrix is product of the font matrix and the ctm associated
with the scaled font, and hence is the matrix mapping from font space to
device space.
Since: 1.8
.. method:: text_extents()
:param utf8: text (str or unicode), encoded in UTF-8
:returns: (x_bearing, y_bearing, width, height, x_advance, y_advance), a tuple of float values.
Gets the extents for a string of text. The extents describe a user-space
rectangle that encloses the "inked" portion of the text drawn at the
origin (0,0) (as it would be drawn by :meth:`Context.show_text` if the cairo
graphics state were set to the same font_face, font_matrix, ctm, and
font_options as *ScaledFont*). Additionally, the x_advance and
y_advance values indicate the amount by which the current point would be
advanced by :meth:`Context.show_text`.
Note that whitespace characters do not directly contribute to the size
of the rectangle (width and 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.
Since: 1.2
class FontOptions()
===================
An opaque structure holding all options that are used when rendering fonts.
Individual features of a *FontOptions* can be set or accessed using functions
named *FontOptions.set_<feature_name>* and
*FontOptions.get_<feature_name>*, like :meth:`FontOptions.set_antialias`
and :meth:`FontOptions.get_antialias`.
New features may be added to a *FontOptions* in the future. For this reason,
:meth:`FontOptions.copy()`, :meth:`FontOptions.equal()`,
:meth:`FontOptions.merge()`, and :meth:`FontOptions.hash()` should be used to
copy, check for equality, merge, or compute a hash value of FontOptions
objects.
.. class:: FontOptions()
:returns: a newly allocated *FontOptions*.
Allocates a new *FontOptions* object with all options initialized to default values.
.. method:: get_antialias()
:returns: the antialiasing mode for the *FontOptions* object
Gets the antialiasing mode for the *FontOptions* object.
See the documentation for :ref:`antialias <mattributes_antialias>`
for full details.
.. method:: get_hint_metrics()
:returns: the metrics hinting mode for the *FontOptions* object
Gets the metrics hinting mode for the *FontOptions* object.
See the documentation for :ref:`hint metrics <mattributes_hint_metrics>`
for full details.
.. method:: get_hint_style()
:returns: the hint style for the *FontOptions* object
Gets the hint style for font outlines for the *FontOptions* object.
See the documentation for :ref:`hint style <mattributes_hint_style>`
for full details.
.. method:: get_subpixel_order()
:returns: the subpixel order for the *FontOptions* object
Gets the subpixel order for the *FontOptions* object.
See the documentation for :ref:`subpixel order <mattributes_subpixel>`
for full details.
.. method:: set_antialias(antialias)
:param antialias: the new antialiasing mode
Sets the antialiasing mode for the *FontOptions* object. This specifies
the type of antialiasing to do when rendering text.
See the documentation for :ref:`antialias <mattributes_antialias>`
for full details.
.. method:: set_hint_metrics(hint_metrics)
:param hint_metrics: the new metrics hinting mode
Sets the metrics hinting mode for the *FontOptions* object. This controls
whether metrics are quantized to integer values in device units.
See the documentation for :ref:`hint metrics <mattributes_hint_metrics>`
for full details.
.. method:: set_hint_style(hint_style)
:param hint_style: the new hint style
Sets the hint style for font outlines for the *FontOptions* object. This
controls whether to fit font outlines to the pixel grid, and if so,
whether to optimize for fidelity or contrast.
See the documentation for :ref:`hint style <mattributes_hint_style>`
for full details.
.. method:: set_subpixel_order(subpixel_order)
:param subpixel_order: the new subpixel order
Sets the subpixel order for the *FontOptions* object. The subpixel order
specifies the order of color elements within each pixel on the display
device when rendering with an antialiasing mode of
:attr:`cairo.ANTIALIAS_SUBPIXEL`.
See the documentation for :ref:`subpixel order <mattributes_subpixel>`
for full details.
- Previous message: [cairo-commit] pycairo/doc c-api.rst, NONE, 1.1 conf.py, NONE, 1.1 faq.rst, NONE, 1.1 index.rst, NONE, 1.1 Makefile.am, 1.2, 1.3 overview.rst, NONE, 1.1 README, NONE, 1.1
- Next message: [cairo-commit] pycairo ChangeLog,1.282,1.283
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]
More information about the cairo-commit
mailing list