[cairo-commit] pycairo/doc/reference context.rst, 1.3, 1.4 exceptions.rst, 1.1, 1.2 index.rst, 1.2, 1.3 matrix.rst, 1.3, 1.4 paths.rst, 1.1, 1.2 patterns.rst, 1.3, 1.4 surfaces.rst, 1.7, 1.8 text.rst, 1.2, 1.3

Steve Chaplin commit at pdx.freedesktop.org
Sat Jun 20 23:23:21 PDT 2009


Committed by: stevech1097

Update of /cvs/cairo/pycairo/doc/reference
In directory kemper:/tmp/cvs-serv1282/doc/reference

Modified Files:
	context.rst exceptions.rst index.rst matrix.rst paths.rst 
	patterns.rst surfaces.rst text.rst 
Log Message:
'SC'

Index: context.rst
===================================================================
RCS file: /cvs/cairo/pycairo/doc/reference/context.rst,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- context.rst	7 Jan 2009 03:03:54 -0000	1.3
+++ context.rst	21 Jun 2009 06:23:18 -0000	1.4
@@ -1,238 +1,1486 @@
 .. _context:
 
-**************************
-Cairo Context (incomplete)
-**************************
+*************
+Cairo Context
+*************
+
+.. currentmodule:: cairo
 
[...1532 lines suppressed...]
+
+      Transform a coordinate from user space to device space by multiplying
+      the given point by the current transformation matrix (CTM).
+
+   .. method:: user_to_device_distance(dx, dy)
+
+      :param dx: X value of a distance vector
+      :type dx: float
+      :param dy: Y value of a distance vector
+      :type dy: float
+      :returns: (dx, dy)
+      :rtype: (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 :meth:`Context.user_to_device` except that the
+      translation components of the CTM will be ignored when transforming
+      *(dx,dy)*.

Index: exceptions.rst
===================================================================
RCS file: /cvs/cairo/pycairo/doc/reference/exceptions.rst,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- exceptions.rst	10 Dec 2008 06:57:46 -0000	1.1
+++ exceptions.rst	21 Jun 2009 06:23:18 -0000	1.2
@@ -4,6 +4,8 @@
 Exceptions
 **********
 
+.. currentmodule:: cairo
+
 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.

Index: index.rst
===================================================================
RCS file: /cvs/cairo/pycairo/doc/reference/index.rst,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- index.rst	1 Jan 2009 05:05:45 -0000	1.2
+++ index.rst	21 Jun 2009 06:23:18 -0000	1.3
@@ -1,15 +1,17 @@
 .. _reference_index:
 
-**********************
-Reference (incomplete)
-**********************
+*********
+Reference
+*********
+
+.. currentmodule:: cairo
 
 .. toctree::
    :maxdepth: 2
 
-   exceptions
-   mattributes
+   constants
    context
+   exceptions
    matrix
    paths
    patterns

Index: matrix.rst
===================================================================
RCS file: /cvs/cairo/pycairo/doc/reference/matrix.rst,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- matrix.rst	13 Jun 2009 11:37:30 -0000	1.3
+++ matrix.rst	21 Jun 2009 06:23:18 -0000	1.4
@@ -4,6 +4,9 @@
 Matrix
 ******
 
+.. currentmodule:: cairo
+
+
 class Matrix()
 ==============
 
@@ -73,24 +76,21 @@
      matrix = cairo.Matrix(xx=sy, yy=sy)
 
 
-   .. method:: init_rotate(radians)
+   .. classmethod:: 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*.
+      :returns: 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
+      :raises: :exc:`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
@@ -141,12 +141,12 @@
       :param dy: Y component of a distance vector.
       :type dy: float
       :returns: the transformed distance vector (dx,dy)
-      :rtype: 2-tuple of float
+      :rtype: (float, 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::
+      :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
@@ -164,7 +164,7 @@
       :param y: Y position.
       :type y: float
       :returns: the transformed point (x,y)
-      :rtype: 2-tuple of float
+      :rtype: (float, float)
 
       Transforms the point *(x, y)* by *Matrix*.
 

Index: paths.rst
===================================================================
RCS file: /cvs/cairo/pycairo/doc/reference/paths.rst,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- paths.rst	10 Dec 2008 06:57:46 -0000	1.1
+++ paths.rst	21 Jun 2009 06:23:18 -0000	1.2
@@ -4,12 +4,20 @@
 Paths
 *****
 
+.. currentmodule:: cairo
+
 class Path()
 ============
 
-*Path* cannot be instantiated directly, it is created by calling
-:meth:`Context.copy_path` and :meth:`Context.copy_path_flat`.
+.. class:: Path()
 
-Path is an iterator, see examples/warpedtext.py for example usage.
+   *Path* cannot be instantiated directly, it is created by calling
+   :meth:`Context.copy_path` and :meth:`Context.copy_path_flat`.
 
-str(path) lists the path elements.
+   str(path) lists the path elements.
+
+   See :ref:`PATH attributes <constants_PATH>`
+
+   Path is an iterator.
+
+   See examples/warpedtext.py for example usage.

Index: patterns.rst
===================================================================
RCS file: /cvs/cairo/pycairo/doc/reference/patterns.rst,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- patterns.rst	16 Mar 2009 09:19:44 -0000	1.3
+++ patterns.rst	21 Jun 2009 06:23:18 -0000	1.4
@@ -4,6 +4,8 @@
 Patterns
 ********
 
+.. currentmodule:: cairo
+
 
 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
@@ -27,7 +29,7 @@
       :rtype: int
 
       Gets the current extend mode for the *Pattern*. See
-      :ref:`EXTEND attributes <mattributes_extend>`
+      :ref:`EXTEND attributes <constants_EXTEND>`
       for details on the semantics of each extend strategy.
 
    .. method:: get_matrix()
@@ -36,19 +38,18 @@
 
    .. method:: set_extend(extend)
 
-      :param extend: an extend describing how the area outside of the *Pattern* will be drawn
+      :param extend: an :ref:`EXTEND <constants_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.
+      Sets the mode to be used for drawing outside the area of a *Pattern*.
 
-      The default extend mode is :attr:`cairo.EXTEND_NONE` for
-      :class:`SurfacePattern` and :attr:`cairo.EXTEND_PAD` for
+      The default extend mode is :data:`cairo.EXTEND_NONE` for
+      :class:`SurfacePattern` and :data:`cairo.EXTEND_PAD` for
       :class:`Gradient` Patterns.
 
    .. method:: set_matrix(matrix)
 
-      :param matrix: a cairo matrix (:class:`Matrix`)
+      :param matrix: a :class:`Matrix`
 
       Sets the *Pattern's* transformation matrix to *matrix*. This matrix is a
       transformation from user space to pattern space.
@@ -112,19 +113,13 @@
 .. 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.
+   :returns: a newly created *SurfacePattern* for the given surface.
+   :raises: *MemoryError* in case of no memory.
 
    .. 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.
+      :returns: the current :ref:`FILTER <constants_filter>` used for
+        resizing the *SurfacePattern*.
 
    .. method:: get_surface()
 
@@ -134,11 +129,8 @@
 
    .. 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.
+      :param filter: a :ref:`FILTER <constants_filter>` describing the filter
+        to use for resizing the *Pattern*
 
       Note that you might want to control filtering even when you do not have
       an explicit *Pattern* object, (for example when using

Index: surfaces.rst
===================================================================
RCS file: /cvs/cairo/pycairo/doc/reference/surfaces.rst,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -d -r1.7 -r1.8
--- surfaces.rst	25 Mar 2009 07:12:09 -0000	1.7
+++ surfaces.rst	21 Jun 2009 06:23:18 -0000	1.8
@@ -1,12 +1,42 @@
 .. _surfaces:
 
-*********************
-Surfaces (incomplete)
-*********************
+********
+Surfaces
+********
+
+.. currentmodule:: cairo
+
+.. comment block
+   example reST:
+   (add back '..' where required at column 0)
+ . class:: module.C[(signature)]
+   .. classmethod:: name(signature)
+   .. staticmethod:: name(signature)
+   .. method:: method(signature)
+
+      :param p1: xxx
+      :type p1: int
+      :param p2: xxx
+      :type p2: str
+      :returns: xxx
+      :rtype: list of strings
+      :raises: xxx
+
+      .. versionadded:: 1.6
+   links:
+     :data:`cairo.ANTIALIAS_SUBPIXEL`
+     :class:`Context`
+     :exc:`cairo.Error`
+     :meth:`.copy_page`
+     :meth:`Context.copy_page`
+     :ref:`LINE_CAP <constants_LINE_CAP>`
+
+     ``ctx.rel_move_to(dx, dy)``   # code snippet
+
 
 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`.
+:class:`Context`.
 
 A cairo.Surface is created by using backend-specific constructors
 of the form cairo.<XXX>Surface().
@@ -16,8 +46,8 @@
 
 .. class:: Surface()
 
-*Surface* is the abstract base class from which all the other surface classes
-derive. It cannot be instantiated directly.
+   *Surface* is the abstract base class from which all the other surface
+   classes derive. It cannot be instantiated directly.
 
    .. method:: copy_page()
 
@@ -32,7 +62,8 @@
 
    .. method:: create_similar(content, width, height)
 
-      :param content: the content for the new surface
+      :param content: the :ref:`CONTENT <constants_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)
@@ -46,9 +77,6 @@
       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.)
 
@@ -71,11 +99,9 @@
 
    .. 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>`.
+      :returns: The :ref:`CONTENT <constants_CONTENT>` type of *Surface*,
+        which indicates whether the *Surface* contains color and/or alpha
+        information.
 
       .. versionadded:: 1.2
 
@@ -86,7 +112,8 @@
         * 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`.
+      This method returns the previous device offset set by
+      :meth:`.set_device_offset`.
 
       .. versionadded:: 1.2
 
@@ -213,11 +240,11 @@
 
 A *cairo.ImageSurface* provides the ability to render to memory buffers either
 allocated by cairo or by the calling code. The supported image formats are
-those defined in :ref:`FORMAT attributes <mattributes_format>`.
+those defined in :ref:`FORMAT attributes <constants_FORMAT>`.
 
 .. class:: ImageSurface(format, width, height)
 
-   :param format: format of pixels in the surface to create
+   :param format: :ref:`FORMAT <constants_FORMAT>` of pixels in the surface to create
    :param width: width of the surface, in pixels
    :param height: height of the surface, in pixels
    :returns: a new *ImageSurface*
@@ -228,17 +255,17 @@
    color or alpha channel belonging to format will be 0. The contents of bits
    within a pixel, but not belonging to the given format are undefined).
 
-   .. method:: create_for_data(data, format, width, height, stride)
+   .. classmethod:: create_for_data(data, format, width, height, stride)
 
       :param data: a writable Python buffer object
-      :param format: the format of pixels in the buffer
+      :param format: the :ref:`FORMAT <constants_FORMAT>` of pixels in the buffer
       :param width: the width of the image to be stored in the buffer
       :param height: the height of the image to be stored in the buffer
       :param stride: the number of bytes between the start of rows in the buffer as allocated. This value should always be computed by :meth:`.format_stride_for_width` before allocating the data buffer.
       :returns: a new *ImageSurface*
       :raises: *MemoryError* in case of no memory.
 
-               :class:`cairo.Error` in case of invalid *stride* value.
+               :exc:`cairo.Error` in case of invalid *stride* value.
 
       Creates an *ImageSurface* for the provided pixel data. The initial
       contents of buffer will be used as the initial image contents; you must
@@ -254,16 +281,14 @@
       data and to create the *ImageSurface*. See
       :meth:`.format_stride_for_width` for example code.
 
-   .. method:: create_from_png(fobj)
+   .. classmethod:: create_from_png(fobj)
 
       :param fobj: a filename, file, or file-like object of the PNG to load.
-
-      Creates a new *ImageSurface* and initializes the contents to the given
-      PNG file.
+      :returns: a new *ImageSurface* initialized the contents to the given PNG file.
 
    .. method:: format_stride_for_width(format, width)
 
-      :param format: a cairo :ref:`format <mattributes_format>` value
+      :param format: a cairo :ref:`FORMAT <constants_FORMAT>` value
       :param width: the desired width of an *ImageSurface* to be created.
       :returns: the appropriate stride to use given the desired format and width, or -1 if either the format is invalid or the width too large.
 
@@ -285,13 +310,13 @@
 
    .. method:: get_format()
 
-      :returns: the :ref:`format <mattributes_format>` of the surface.
+      :returns: the :ref:`FORMAT <constants_FORMAT>` of the *ImageSurface*.
 
       .. versionadded:: 1.2
 
    .. method:: get_height()
 
-      :returns: the height of the surface in pixels.
+      :returns: the height of the *ImageSurface* in pixels.
 
    .. method:: get_stride()
 
@@ -299,7 +324,7 @@
 
    .. method:: get_width()
 
-      :returns: the width of the surface in pixels.
+      :returns: the width of the *ImageSurface* in pixels.
 
 
 class PDFSurface(:class:`Surface`)
@@ -312,22 +337,25 @@
 
    :param fobj: a filename or writable file object
    :type fobj: str, file or file-like object
-   :param width_in_points: width of the surface, in points (1 point == 1/72.0 inch)
+   :param width_in_points: width of the surface, in points
+     (1 point == 1/72.0 inch)
    :type  width_in_points: float
-   :param height_in_points: height of the surface, in points (1 point == 1/72.0 inch)
+   :param height_in_points: height of the surface, in points
+     (1 point == 1/72.0 inch)
    :type  height_in_points: float
-   :returns: a new *PDFSurface*
+   :returns: a new *PDFSurface* of the specified size in points to be written
+     to *fobj*.
    :raises: *MemoryError* in case of no memory
 
-   Creates a *PDFSurface* of the specified size in points to be written to *fobj*.
-
    .. versionadded:: 1.2
 
    .. method:: set_size()
 
-      :param width_in_points: new surface width, in points (1 point == 1/72.0 inch)
+      :param width_in_points: new surface width, in points
+        (1 point == 1/72.0 inch)
       :type  width_in_points: float
-      :param height_in_points: new surface height, in points (1 point == 1/72.0 inch)
+      :param height_in_points: new surface height, in points
+        (1 point == 1/72.0 inch)
       :type  height_in_points: float
 
       Changes the size of a *PDFSurface* for the current (and subsequent) pages.
@@ -351,72 +379,195 @@
 
    :param fobj:  a filename or writable file object
    :type fobj: str, file or file-like object
-   :param width_in_points: width of the surface, in points (1 point == 1/72.0 inch)
+   :param width_in_points: width of the surface, in points
+     (1 point == 1/72.0 inch)
    :type  width_in_points: float
-   :param height_in_points: height of the surface, in points (1 point == 1/72.0 inch)
+   :param height_in_points: height of the surface, in points
+     (1 point == 1/72.0 inch)
    :type  height_in_points: float
-   :returns: a new *PDFSurface*
+   :returns: a new *PDFSurface* of the specified size in points to be written
+     to *fobj*.
    :raises: *MemoryError* in case of no memory
 
-   Creates a *PSSurface* of the specified size in points to be written to
-   *fobj*.
-
    Note that the size of individual pages of the PostScript output can
-   vary. See :meth:`PSSurface.set_size`.
+   vary. See :meth:`.set_size`.
 
    .. method:: dsc_begin_page_setup()
 
       This method indicates that subsequent calls to
-      :meth:`PSSurface.dsc_comment` should direct comments to the PageSetup
+      :meth:`.dsc_comment` should direct comments to the PageSetup
       section of the PostScript output.
 
-      This method call is only needed for the first page of a surface. It should
-      be called after any call to :meth:`PSSurface.dsc_begin_setup` and before
-      any drawing is performed to the surface.
+      This method call is only needed for the first page of a surface. It
+      should be called after any call to :meth:`.dsc_begin_setup` and
+      before any drawing is performed to the surface.
 
-      See :meth:`PSSurface.dsc_comment` for more details.
+      See :meth:`.dsc_comment` for more details.
 
       .. versionadded:: 1.2
 
    .. method:: dsc_begin_setup()
 
-      This function indicates that subsequent calls to
-      :meth:`PSSurface.dsc_comment` should direct comments to the Setup
-      section of the PostScript output.
+      This function indicates that subsequent calls to :meth:`.dsc_comment`
+      should direct comments to the Setup section of the PostScript output.
 
       This function should be called at most once per surface, and must be
-      called before any call to :meth:`PSSurface.dsc_begin_page_setup` and
-      before any drawing is performed to the surface.
+      called before any call to :meth:`.dsc_begin_page_setup` and before any
+      drawing is performed to the surface.
 
-      See :meth:`PSSurface.dsc_comment` for more details.
+      See :meth:`.dsc_comment` for more details.
 
       .. versionadded:: 1.2
 
-   .. method:: dsc_comment()
+   .. method:: dsc_comment(comment)
+
+      :param comment: a comment string to be emitted into the PostScript output
+      :type comment: str
 
+      Emit a comment into the PostScript output for the given surface.
+
+      The comment is expected to conform to the PostScript Language
+      Document Structuring Conventions (DSC). Please see that manual for
+      details on the available comments and their meanings. In
+      particular, the %%IncludeFeature comment allows a
+      device-independent means of controlling printer device features. So
+      the PostScript Printer Description Files Specification will also be
+      a useful reference.
+
+      The comment string must begin with a percent character (%) and the
+      total length of the string (including any initial percent
+      characters) must not exceed 255 characters. Violating either of
+      these conditions will place *PSSurface* into an error state. But
+      beyond these two conditions, this function will not enforce
+      conformance of the comment with any particular specification.
+
+      The comment string should not have a trailing newline.
+
+      The DSC specifies different sections in which particular comments
+      can appear. This function provides for comments to be emitted
+      within three sections: the header, the Setup section, and the
+      PageSetup section.  Comments appearing in the first two sections
+      apply to the entire document while comments in the BeginPageSetup
+      section apply only to a single page.
+
+      For comments to appear in the header section, this function should
+      be called after the surface is created, but before a call to
+      :meth:`.dsc_begin_setup`.
+
+      For comments to appear in the Setup section, this function should be
+      called after a call to :meth:`.dsc_begin_setup` but before a call to
+      :meth:`.dsc_begin_page_setup`.
+
+      For comments to appear in the PageSetup section, this function should be
+      called after a call to :meth:`.dsc_begin_page_setup`.
+
+      Note that it is only necessary to call :meth:`.dsc_begin_page_setup` for
+      the first page of any surface. After a call to :meth:`Context.show_page`
+      or :meth:`Context.copy_page` comments are unambiguously directed to the
+      PageSetup section of the current page. But it doesn't hurt to call this
+      function at the beginning of every page as that consistency may make the
+      calling code simpler.
+
+      As a final note, cairo automatically generates several comments on
+      its own. As such, applications must not manually generate any of
+      the following comments:
+
+      Header section: %!PS-Adobe-3.0, %Creator, %CreationDate, %Pages,
+      %BoundingBox, %DocumentData, %LanguageLevel, %EndComments.
+
+      Setup section: %BeginSetup, %EndSetup
+
+      PageSetup section: %BeginPageSetup, %PageBoundingBox,
+      %EndPageSetup.
+
+      Other sections: %BeginProlog, %EndProlog, %Page, %Trailer, %EOF
+
+      Here is an example sequence showing how this function might be used::
+
+        surface = PSSurface (filename, width, height)
+        ...
+        surface.dsc_comment (surface, "%%Title: My excellent document")
+        surface.dsc_comment (surface, "%%Copyright: Copyright (C) 2006 Cairo Lover")
+        ...
+        surface.dsc_begin_setup (surface)
+        surface.dsc_comment (surface, "%%IncludeFeature: *MediaColor White")
+        ...
+        surface.dsc_begin_page_setup (surface)
+        surface.dsc_comment (surface, "%%IncludeFeature: *PageSize A3")
+        surface.dsc_comment (surface, "%%IncludeFeature: *InputSlot LargeCapacity")
+        surface.dsc_comment (surface, "%%IncludeFeature: *MediaType Glossy")
+        surface.dsc_comment (surface, "%%IncludeFeature: *MediaColor Blue")
+        ... draw to first page here ..
+        ctx.show_page (cr)
+        ...
+        surface.dsc_comment (surface, "%%IncludeFeature:  PageSize A5");
+        ...
 
       .. versionadded:: 1.2
 
    .. method:: get_eps()
 
+      :returns: True iff the *PSSurface* will output Encapsulated PostScript.
 
       .. versionadded:: 1.6
 
-   .. method:: ps_level_to_string()
+   .. staticmethod:: ps_level_to_string(level)
 
+      :param level: a :ref:`PS_LEVEL <constants_PS_LEVEL>`
+      :returns: the string associated to given level.
+      :rtype: str
+      :raises: :exc:`cairo.Error` if *level* isn't valid.
+
+      Get the string representation of the given *level*.  See
+      :meth:`.ps_get_levels` for a way to get the list of valid level
+      ids.
 
       .. versionadded:: 1.6
 
-   .. method:: restrict_to_level()
+   .. method:: restrict_to_level(level)
+
+      :param level: a :ref:`PS_LEVEL <constants_PS_LEVEL>`
+
+      Restricts the generated PostSript file to *level*. See
+      :meth:`.ps_get_levels` for a list of available level values that
+      can be used here.
 
+      This function should only be called before any drawing operations have
+      been performed on the given surface. The simplest way to do this is to
+      call this function immediately after creating the surface.
 
       .. versionadded:: 1.6
 
-   .. method:: set_eps()
+   .. method:: set_eps(eps)
+
+      :param eps: True to output EPS format PostScript
+      :type eps: bool
+
+      If *eps* is True, the PostScript surface will output Encapsulated
+      PostScript.
+
+      This function should only be called before any drawing operations have
+      been performed on the current page. The simplest way to do this is to
+      call this function immediately after creating the surface. An
+      Encapsulated PostScript file should never contain more than one page.
 
       .. versionadded:: 1.6
 
-   .. method:: set_size()
+   .. method:: set_size(width_in_points, height_in_points)
+
+      :param width_in_points: new surface width, in points (1 point == 1/72.0 inch)
+      :param height_in_points: new surface height, in points (1 point == 1/72.0 inch)
+      :type width_in_points: float
+      :type height_in_points: float
+
+      Changes the size of a PostScript surface for the current (and
+      subsequent) pages.
+
+      This function should only be called before any drawing operations
+      have been performed on the current page. The simplest way to do
+      this is to call this function immediately after creating the
+      surface or immediately after completing a page with either
+      :meth:`Context.show_page` or :meth:`Context.copy_page`.
 
       .. versionadded:: 1.2
 
@@ -424,27 +575,61 @@
 class SVGSurface(:class:`Surface`)
 ==================================
 
-.. class:: SVGSurface
+The *SVGSurface* is used to render cairo graphics to SVG files and is a
+multi-page vector surface backend
 
-.. comment
- Py: surface = cairo.SVGSurface (f, width_in_points, height_in_points)
-     where 'f' is a filename, a file object, or a file-like object
+.. class:: SVGSurface(fobj, width_in_points, height_in_points)
+
+   :param fobj:  a filename or writable file object
+   :type fobj: str, file or file-like object
+   :param width_in_points: width of the surface, in points (1 point == 1/72.0 inch)
+   :type  width_in_points: float
+   :param height_in_points: height of the surface, in points (1 point == 1/72.0 inch)
+   :type  height_in_points: float
+   :returns: a new *SVGSurface* of the specified size in points to be written to *fobj*.
+   :raises: *MemoryError* in case of no memory
 
- C:  surface = cairo_svg_surface_create (filename, width_in_points,
- 				        height_in_points);
-..
+
+   .. method:: get_versions
+
+      Not implemented in pycairo (yet)
+
+   .. method:: restrict_to_version
+
+      Not implemented in pycairo (yet)
+
+   .. method:: version_to_string
+
+      Not implemented in pycairo (yet)
 
 
 class Win32Surface(:class:`Surface`)
 ====================================
 
-.. class:: Win32Surface
+The Microsoft Windows surface is used to render cairo graphics to Microsoft
+Windows windows, bitmaps, and printing device contexts.
 
+.. class:: Win32Surface(hdc)
+
+   :param hdc: the DC to create a surface for
+   :type hdc: int
+   :returns: the newly created surface
+
+   Creates a cairo surface that targets the given DC. The DC will be queried
+   for its initial clip extents, and this will be used as the size of the
+   cairo surface. The resulting surface will always be of format
+   cairo.FORMAT_RGB24, see :ref:`FORMAT attributes <constants_FORMAT>`.
 
 
 class XlibSurface(:class:`Surface`)
 ===================================
 
+The XLib surface is used to render cairo graphics to X Window System windows
+and pixmaps using the XLib library.
+
+Note that the XLib surface automatically takes advantage of X render extension
+if it is available.
+
 .. class:: XlibSurface
 
    *XlibSurface* cannot be instantiated directly. But an XlibSurface instance
@@ -452,8 +637,18 @@
 
    .. method:: get_depth()
 
+      :returns: the number of bits used to represent each pixel value.
+
+      .. versionadded:: 1.2
 
    .. method:: get_height()
 
+      :returns: the height of the X Drawable underlying the surface in pixels.
+
+      .. versionadded:: 1.2
 
    .. method:: get_width()
+
+      :returns: the width of the X Drawable underlying the surface in pixels.
+
+      .. versionadded:: 1.2

Index: text.rst
===================================================================
RCS file: /cvs/cairo/pycairo/doc/reference/text.rst,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- text.rst	12 Feb 2009 09:04:29 -0000	1.2
+++ text.rst	21 Jun 2009 06:23:18 -0000	1.3
@@ -4,11 +4,25 @@
 Text
 ****
 
+.. currentmodule:: cairo
+
 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 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/.
+* 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/.
 
 
 
@@ -27,7 +41,8 @@
 
 .. class:: FontFace()
 
-   .. note:: This class cannot be instantiated directly, it is returned by :meth:`Context.get_font_face`.
+   .. note:: This class cannot be instantiated directly, it is returned by
+     :meth:`Context.get_font_face`.
 
 
 
@@ -36,16 +51,14 @@
 
 The *cairo.ToyFontFace* class can be used instead of :meth:`Context.select_font_face` to create a toy font independently of a context.
 
-.. class:: ToyFontFace(family, [slant[, weight]])
+.. class:: ToyFontFace(family[, slant[, weight]])
 
    :param family: a font family name, encoded in UTF-8
    :type family: str
-   :param slant: the slant of the font, by default
-        :attr:`cairo.FONT_SLANT_NORMAL`.  See :ref:`SLANT attributes
-        <mattributes_slant>` for details of the slant values available.
-   :param weight: the weight of the font, by default
-        :attr:`cairo.FONT_WEIGHT_NORMAL`.  See :ref:`WEIGHT attributes
-	<mattributes_weight>` for details of the available weights.
+   :param slant: the :ref:`FONT_SLANT <constants_FONT_SLANT>` of the font,
+     defaults to :data:`cairo.FONT_SLANT_NORMAL`.
+   :param weight: the :ref:`FONT_WEIGHT <constants_FONT_WEIGHT>` of the font,
+     defaults to :data:`cairo.FONT_WEIGHT_NORMAL`.
    :returns: a new *ToyFontFace*
 
    Creates a *ToyFontFace* from a triplet of family, slant, and weight. These
@@ -71,17 +84,13 @@
 
    .. method:: get_slant()
 
-      :returns: the slant value
-
-      Gets the slant a toy font.
+      :returns: the :ref:`FONT_SLANT <constants_FONT_SLANT>` value
 
       .. versionadded:: 1.8.4
 
    .. method:: get_weight()
 
-      :returns: the weight value
-
-      Gets the weight a toy font.
+      :returns: the :ref:`FONT_WEIGHT <constants_FONT_WEIGHT>` value
 
       .. versionadded:: 1.8.4
 
@@ -100,13 +109,14 @@
 .. 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.
+   :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.
@@ -117,12 +127,24 @@
 
       Gets the metrics for a *ScaledFont*.
 
+   .. method:: get_ctm()
+
+      Not implemented in pycairo (yet)
+
    .. method:: get_font_face()
 
       :returns: the :class:`FontFace` that this *ScaledFont* was created for.
 
       .. versionadded:: 1.2
 
+   .. method:: get_font_matrix()
+
+      Not implemented in pycairo (yet)
+
+   .. method:: get_font_options()
+
+      Not implemented in pycairo (yet)
+
    .. method:: get_scale_matrix()
 
       :returns: the scale :class:`Matrix`
@@ -134,6 +156,11 @@
       .. versionadded:: 1.8
 
 
+   .. method:: glyph_extents()
+
+      Not implemented in pycairo (yet)
+
+
    .. method:: text_extents()
 
       :param utf8: text (str or unicode), encoded in UTF-8
@@ -155,6 +182,11 @@
 
       .. versionadded:: 1.2
 
+   .. method:: text_to_glyphs()
+
+      Not implemented in pycairo (yet)
+
+
 
 class FontOptions()
 ===================
@@ -180,71 +212,44 @@
 
    .. 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.
+      :returns: the :ref:`ANTIALIAS <constants_ANTIALIAS>` mode for the *FontOptions* object
 
    .. 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.
+      :returns: the :ref:`HINT METRICS <constants_HINT_METRICS>` mode for the *FontOptions* object
 
    .. 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.
+      :returns: the :ref:`HINT STYLE <constants_HINT_STYLE>` for the *FontOptions* object
 
    .. 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.
+      :returns: the :ref:`SUBPIXEL_ORDER <constants_SUBPIXEL_ORDER>` for the *FontOptions* object
 
    .. method:: set_antialias(antialias)
 
-      :param antialias: the new antialiasing mode
+      :param antialias: the :ref:`ANTIALIAS <constants_ANTIALIAS>` 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.
+      This specifies the type of antialiasing to do when rendering text.
 
    .. method:: set_hint_metrics(hint_metrics)
 
-      :param hint_metrics: the new metrics hinting mode
+      :param hint_metrics: the :ref:`HINT METRICS <constants_HINT_METRICS>` 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.
+      This controls whether metrics are quantized to integer values in device
+      units.
 
    .. method:: set_hint_style(hint_style)
 
-      :param hint_style: the new hint style
+      :param hint_style: the :ref:`HINT STYLE <constants_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,
+      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
+      :param subpixel_order: the :ref:`SUBPIXEL_ORDER <constants_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.
+      The subpixel order specifies the order of color elements within each
+      pixel on the display device when rendering with an antialiasing mode of
+      :data:`cairo.ANTIALIAS_SUBPIXEL`.



More information about the cairo-commit mailing list