Enums — Pycairo documentation

# Enums

Before Pycairo 1.13 most of the enum values defined here where only available as constants on the module level. See Legacy Constants.

class cairo.Antialias(value: int)

  Specifies the type of antialiasing to do when rendering text or shapes.

  Added in version 1.13.

  BEST: Antialias = Ellipsis

    Hint that the backend should render at the highest quality, sacrificing speed if necessary.

  DEFAULT: Antialias = Ellipsis

    Use the default antialiasing for the subsystem and target device

  FAST: Antialias = Ellipsis

    Hint that the backend should perform some antialiasing but prefer speed over quality.

  GOOD: Antialias = Ellipsis

    The backend should balance quality against performance.

  GRAY: Antialias = Ellipsis

    Perform single-color antialiasing (using shades of gray for black text on a white background, for example).

  NONE: Antialias = Ellipsis

    Use a bilevel alpha mask

  SUBPIXEL: Antialias = Ellipsis

    Perform antialiasing by taking advantage of the order of subpixel elements on devices such as LCD panels.

class cairo.Content(value: int)

  These constants are used to describe the content that a `Surface` will contain, whether color information, alpha information (translucence vs. opacity), or both.

  Added in version 1.13.

  ALPHA: Content = Ellipsis

    The surface will hold alpha content only.

  COLOR: Content = Ellipsis

    The surface will hold color content only.

  COLOR_ALPHA: Content = Ellipsis

    The surface will hold color and alpha content.

class cairo.Extend(value: int)

  These constants 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 `NONE` for `SurfacePattern` and `PAD` for `Gradient` patterns.

  Added in version 1.13.

  NONE: Extend = Ellipsis

    pixels outside of the source pattern are fully transparent

  PAD: Extend = Ellipsis

    pixels outside of the pattern copy the closest pixel from the source (Since 1.2; but only implemented for surface patterns since 1.6)

  REFLECT: Extend = Ellipsis

    the pattern is tiled by reflecting at the edges (Implemented for surface patterns since 1.6)

  REPEAT: Extend = Ellipsis

    the pattern is tiled by repeating

class cairo.FillRule(value: int)

  These constants 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 `WINDING`.

  Added in version 1.13.

  EVEN_ODD: FillRule = Ellipsis

    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.

  WINDING: FillRule = Ellipsis

    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.

class cairo.Filter(value: int)

  These constants are used to indicate what filtering should be applied when reading pixel values from patterns. See `Pattern.set_filter()` for indicating the desired filter to be used with a particular pattern.

  Added in version 1.13.

  BEST: Filter = Ellipsis

    The highest-quality available, performance may not be suitable for interactive use.

  BILINEAR: Filter = Ellipsis

    Linear interpolation in two dimensions

  FAST: Filter = Ellipsis

    A high-performance filter, with quality similar FILTER_NEAREST

  GAUSSIAN: Filter = Ellipsis

    This filter value is currently unimplemented, and should not be used in current code.

  GOOD: Filter = Ellipsis

    A reasonable-performance filter, with quality similar to FILTER_BILINEAR

  NEAREST: Filter = Ellipsis

    Nearest-neighbor filtering

class cairo.FontSlant(value: int)

  These constants specify variants of a `FontFace` based on their slant.

  Added in version 1.13.

  ITALIC: FontSlant = Ellipsis

    Italic font style

  NORMAL: FontSlant = Ellipsis

    Upright font style

  OBLIQUE: FontSlant = Ellipsis

    Oblique font style

class cairo.FontWeight(value: int)

  These constants specify variants of a `FontFace` based on their weight.

  Added in version 1.13.

  BOLD: FontWeight = Ellipsis

    Bold font weight

  NORMAL: FontWeight = Ellipsis

    Normal font weight

class cairo.Format(value: int)

  These constants are used to identify the memory format of `ImageSurface` data.

  New entries may be added in future versions.

  Added in version 1.13.

  stride_for_width(width: int) → int
    Parameters:

      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.

    This method provides a stride value that will respect all alignment requirements of the accelerated image-rendering code within cairo. Typical usage will be of the form:

        format = cairo.Format.RGB24
        stride = format.stride_for_width(width)
        surface = cairo.ImageSurface.create_for_data(
            data, format, width, height, stride)

    Also available under `cairo.ImageSurface.format_stride_for_width()`.

    Added in version 1.14.

  A1: Format = Ellipsis

    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.

  A8: Format = Ellipsis

    each pixel is a 8-bit quantity holding an alpha value.

  ARGB32: Format = Ellipsis

    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.)

  INVALID: Format = Ellipsis

    no such format exists or is supported.

  RGB16_565: Format = Ellipsis

    each pixel is a 16-bit quantity with red in the upper 5 bits, then green in the middle 6 bits, and blue in the lower 5 bits.

  RGB24: Format = Ellipsis

    each pixel is a 32-bit quantity, with the upper 8 bits unused. [1] Red, Green, and Blue are stored in the remaining 24 bits in that order.

    [1]

    Cairo operators (for example CLEAR and SRC) may overwrite unused bytes as an implementation side-effect, their values should be considered undefined.

  RGB30: Format = Ellipsis

    like `RGB24` but with 10bpc.

  RGB96F: Format = Ellipsis

    3 floats, R, G, B.

    Added in version 1.23: Only available with cairo 1.17.2+

  RGBA128F: Format = Ellipsis

    4 floats, R, G, B, A.

    Added in version 1.23: Only available with cairo 1.17.2+

class cairo.HintMetrics(value: int)

  These constants 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.

  Added in version 1.13.

  DEFAULT: HintMetrics = Ellipsis

    Hint metrics in the default manner for the font backend and target device

  OFF: HintMetrics = Ellipsis

    “Do not hint font metrics

  ON: HintMetrics = Ellipsis

    Hint font metrics

class cairo.HintStyle(value: int)

  These constants 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.

  Added in version 1.13.

  DEFAULT: HintStyle = Ellipsis

    Use the default hint style for font backend and target device

  FULL: HintStyle = Ellipsis

    Hint outlines to maximize contrast

  MEDIUM: HintStyle = Ellipsis

    Hint outlines with medium strength giving a compromise between fidelity to the original shapes and contrast

  NONE: HintStyle = Ellipsis

    Do not hint outlines

  SLIGHT: HintStyle = Ellipsis

    Hint outlines slightly to improve contrast while retaining good fidelity to the original shapes.

class cairo.LineCap(value: int)

  These constants specify how to render the endpoints of the path when stroking.

  The default line cap style is `BUTT`

  Added in version 1.13.

  BUTT: LineCap = Ellipsis

    start(stop) the line exactly at the start(end) point

  ROUND: LineCap = Ellipsis

    use a round ending, the center of the circle is the end point

  SQUARE: LineCap = Ellipsis

    use squared ending, the center of the square is the end point

class cairo.LineJoin(value: int)

  These constants specify how to render the junction of two lines when stroking.

  The default line join style is `MITER`

  Added in version 1.13.

  BEVEL: LineJoin = Ellipsis

    use a cut-off join, the join is cut off at half the line width from the joint point

  MITER: LineJoin = Ellipsis

    use a sharp (angled) corner, see `Context.set_miter_limit()`

  ROUND: LineJoin = Ellipsis

    use a rounded join, the center of the circle is the joint point

class cairo.Operator(value: int)

  These constants are used to set the compositing operator for all cairo drawing operations.

  The default operator is `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 https://cairographics.org/operators.

  Added in version 1.13.

  ADD: Operator = Ellipsis

    source and destination layers are accumulated

  ATOP: Operator = Ellipsis

    draw source on top of destination content and only there

  CLEAR: Operator = Ellipsis

    clear destination layer (bounded)

  COLOR_BURN: Operator = Ellipsis

    darkens the destination color to reflect the source color.

  COLOR_DODGE: Operator = Ellipsis

    brightens the destination color to reflect the source color.

  DARKEN: Operator = Ellipsis

    replaces the destination with the source if it is darker, otherwise keeps the source.

  DEST: Operator = Ellipsis

    ignore the source

  DEST_ATOP: Operator = Ellipsis

    leave destination on top of source content and only there (unbounded)

  DEST_IN: Operator = Ellipsis

    leave destination only where there was source content (unbounded)

  DEST_OUT: Operator = Ellipsis

    leave destination only where there was no source content

  DEST_OVER: Operator = Ellipsis

    draw destination on top of source

  DIFFERENCE: Operator = Ellipsis

    Takes the difference of the source and destination color.

  EXCLUSION: Operator = Ellipsis

    Produces an effect similar to difference, but with lower contrast.

  HARD_LIGHT: Operator = Ellipsis

    Multiplies or screens, dependent on source color.

  HSL_COLOR: Operator = Ellipsis

    Creates a color with the hue and saturation of the source and the luminosity of the target. This preserves the gray levels of the target and is useful for coloring monochrome images or tinting color images.

  HSL_HUE: Operator = Ellipsis

    Creates a color with the hue of the source and the saturation and luminosity of the target.

  HSL_LUMINOSITY: Operator = Ellipsis

    Creates a color with the luminosity of the source and the hue and saturation of the target. This produces an inverse effect to `HSL_COLOR`

  HSL_SATURATION: Operator = Ellipsis

    Creates a color with the saturation of the source and the hue and luminosity of the target. Painting with this mode onto a gray area produces no change.

  IN: Operator = Ellipsis

    draw source where there was destination content (unbounded)

  LIGHTEN: Operator = Ellipsis

    replaces the destination with the source if it is lighter, otherwise keeps the source.

  MULTIPLY: Operator = Ellipsis

    source and destination layers are multiplied. This causes the result to be at least as dark as the darker inputs.

  OUT: Operator = Ellipsis

    draw source where there was no destination content (unbounded)

  OVER: Operator = Ellipsis

    draw source layer on top of destination layer (bounded)

  OVERLAY: Operator = Ellipsis

    multiplies or screens, depending on the lightness of the destination color.

  SATURATE: Operator = Ellipsis

    like over, but assuming source and dest are disjoint geometries

  SCREEN: Operator = Ellipsis

    source and destination are complemented and multiplied. This causes the result to be at least as light as the lighter inputs.

  SOFT_LIGHT: Operator = Ellipsis

    Darkens or lightens, dependent on source color.

  SOURCE: Operator = Ellipsis

    replace destination layer (bounded)

  XOR: Operator = Ellipsis

    source and destination are shown where there is only one of them

class cairo.PathDataType(value: int)

  These constants are used to describe the type of one portion of a path when represented as a `Path`.

  Added in version 1.13.

  CLOSE_PATH: PathDataType = Ellipsis

    A close-path operation

  CURVE_TO: PathDataType = Ellipsis

    A curve-to operation

  LINE_TO: PathDataType = Ellipsis

    A line-to operation

  MOVE_TO: PathDataType = Ellipsis

    A move-to operation

class cairo.PSLevel(value: int)

  These constants are used to describe the language level of the PostScript Language Reference that a generated PostScript file will conform to. Note: the constants are only defined when cairo has been compiled with PS support enabled.

  Added in version 1.13.

  LEVEL_2: PSLevel = Ellipsis

    The language level 2 of the PostScript specification.

  LEVEL_3: PSLevel = Ellipsis

    The language level 3 of the PostScript specification.

class cairo.PDFVersion(value: int)

  These constants are used to describe the version number of the PDF specification that a generated PDF file will conform to.

  Added in version 1.13.

  VERSION_1_4: PDFVersion = Ellipsis

    The version 1.4 of the PDF specification.

  VERSION_1_5: PDFVersion = Ellipsis

    The version 1.5 of the PDF specification.

  VERSION_1_6: PDFVersion = Ellipsis

    The version 1.6 of the PDF specification.

    Added in version 1.23.0: Only available with cairo 1.17.6+

  VERSION_1_7: PDFVersion = Ellipsis

    The version 1.7 of the PDF specification.

    Added in version 1.23.0: Only available with cairo 1.17.6+

class cairo.SVGVersion(value: int)

  These constants are used to describe the version number of the SVG specification that a generated SVG file will conform to.

  Added in version 1.13.

  VERSION_1_1: SVGVersion = Ellipsis

    The version 1.1 of the SVG specification.

  VERSION_1_2: SVGVersion = Ellipsis

    The version 1.2 of the SVG specification.

class cairo.SubpixelOrder(value: int)

  The subpixel order specifies the order of color elements within each pixel on the display device when rendering with an antialiasing mode of `Antialias.SUBPIXEL`.

  Added in version 1.13.

  BGR: SubpixelOrder = Ellipsis

    Subpixel elements are arranged horizontally with blue at the left

  DEFAULT: SubpixelOrder = Ellipsis

    Use the default subpixel order for for the target device

  RGB: SubpixelOrder = Ellipsis

    Subpixel elements are arranged horizontally with red at the left

  VBGR: SubpixelOrder = Ellipsis

    Subpixel elements are arranged vertically with blue at the top

  VRGB: SubpixelOrder = Ellipsis

    Subpixel elements are arranged vertically with red at the top

class cairo.RegionOverlap(value: int)

  Added in version 1.13.

  IN: RegionOverlap = Ellipsis

    The contents are entirely inside the region.

  OUT: RegionOverlap = Ellipsis

    The contents are entirely outside the region.

  PART: RegionOverlap = Ellipsis

    The contents are partially inside and partially outside the region.

class cairo.Status(value: int)

  Added in version 1.13.

  CLIP_NOT_REPRESENTABLE: Status = Ellipsis
  DEVICE_ERROR: Status = Ellipsis
  DEVICE_FINISHED: Status = Ellipsis
  DEVICE_TYPE_MISMATCH: Status = Ellipsis
  FILE_NOT_FOUND: Status = Ellipsis
  FONT_TYPE_MISMATCH: Status = Ellipsis
  INVALID_CLUSTERS: Status = Ellipsis
  INVALID_CONTENT: Status = Ellipsis
  INVALID_DASH: Status = Ellipsis
  INVALID_DSC_COMMENT: Status = Ellipsis
  INVALID_FORMAT: Status = Ellipsis
  INVALID_INDEX: Status = Ellipsis
  INVALID_MATRIX: Status = Ellipsis
  INVALID_MESH_CONSTRUCTION: Status = Ellipsis
  INVALID_PATH_DATA: Status = Ellipsis
  INVALID_POP_GROUP: Status = Ellipsis
  INVALID_RESTORE: Status = Ellipsis
  INVALID_SIZE: Status = Ellipsis
  INVALID_SLANT: Status = Ellipsis
  INVALID_STATUS: Status = Ellipsis
  INVALID_STRIDE: Status = Ellipsis
  INVALID_STRING: Status = Ellipsis
  INVALID_VISUAL: Status = Ellipsis
  INVALID_WEIGHT: Status = Ellipsis
  JBIG2_GLOBAL_MISSING: Status = Ellipsis

    Added in version 1.14.

  LAST_STATUS: Status = Ellipsis
  NEGATIVE_COUNT: Status = Ellipsis
  NO_CURRENT_POINT: Status = Ellipsis
  NO_MEMORY: Status = Ellipsis
  NULL_POINTER: Status = Ellipsis
  PATTERN_TYPE_MISMATCH: Status = Ellipsis
  READ_ERROR: Status = Ellipsis
  SUCCESS: Status = Ellipsis
  SURFACE_FINISHED: Status = Ellipsis
  SURFACE_TYPE_MISMATCH: Status = Ellipsis
  TEMP_FILE_ERROR: Status = Ellipsis
  USER_FONT_ERROR: Status = Ellipsis
  USER_FONT_IMMUTABLE: Status = Ellipsis
  USER_FONT_NOT_IMPLEMENTED: Status = Ellipsis
  WRITE_ERROR: Status = Ellipsis
  TAG_ERROR: Status = Ellipsis

    Added in version 1.18.0: Only available with cairo 1.15.10+

  FREETYPE_ERROR: Status = Ellipsis

    Added in version 1.18.0: Only available with cairo 1.15.10+

  PNG_ERROR: Status = Ellipsis

    Added in version 1.18.0: Only available with cairo 1.15.10+

  WIN32_GDI_ERROR: Status = Ellipsis

    Added in version 1.18.0: Only available with cairo 1.15.10+

  DWRITE_ERROR: Status = Ellipsis

    Added in version 1.23.0: Only available with cairo 1.17.6+

  SVG_FONT_ERROR: Status = Ellipsis

    Added in version 1.25.0: Only available with cairo 1.17.8+

class cairo.ScriptMode(value: int)

  A set of script output variants.

  Added in version 1.14.

  ASCII: ScriptMode = Ellipsis

    the output will be in readable text (default)

  BINARY: ScriptMode = Ellipsis

    the output will use byte codes.

class cairo.TextClusterFlags(value: int)

  Specifies properties of a text cluster mapping.

  Added in version 1.14.

  BACKWARD: TextClusterFlags = Ellipsis

    The clusters in the cluster array map to glyphs in the glyph array from end to start.

class cairo.SurfaceObserverMode(value: int)

  Whether operations should be recorded.

  Added in version 1.14.

  NORMAL: SurfaceObserverMode = Ellipsis

    no recording is done

  RECORD_OPERATIONS: SurfaceObserverMode = Ellipsis

    operations are recorded

class cairo.PDFOutlineFlags(value: int)

  `PDFOutlineFlags` is used by the `PDFSurface.add_outline()` method to specify the attributes of an outline item. These flags may be bitwise-or’d to produce any combination of flags.

  Added in version 1.18.0: Only available with cairo 1.15.10+

  OPEN: PDFOutlineFlags = Ellipsis

    The outline item defaults to open in the PDF viewer

  BOLD: PDFOutlineFlags = Ellipsis

    The outline item is displayed by the viewer in bold text

  ITALIC: PDFOutlineFlags = Ellipsis

    The outline item is displayed by the viewer in italic text

class cairo.SVGUnit(value: int)

  `SVGUnit` is used to describe the units valid for coordinates and lengths in the SVG specification.

  See also:

  - https://www.w3.org/TR/SVG/coords.htmlUnits

  - https://www.w3.org/TR/SVG/types.htmlDataTypeLength

  - https://www.w3.org/TR/css-values-3/lengths

  Added in version 1.18.0: Only available with cairo 1.15.10+

  USER: SVGUnit = Ellipsis

    User unit, a value in the current coordinate system. If used in the root element for the initial coordinate systems it corresponds to pixels.

  EM: SVGUnit = Ellipsis

    The size of the element’s font.

  EX: SVGUnit = Ellipsis

    The x-height of the element’s font.

  PX: SVGUnit = Ellipsis

    Pixels (1px = 1/96th of 1in).

  IN: SVGUnit = Ellipsis

    Inches (1in = 2.54cm = 96px)

  CM: SVGUnit = Ellipsis

    Centimeters (1cm = 96px/2.54).

  MM: SVGUnit = Ellipsis

    Millimeters (1mm = 1/10th of 1cm).

  PT: SVGUnit = Ellipsis

    Points (1pt = 1/72th of 1in).

  PC: SVGUnit = Ellipsis

    Picas (1pc = 1/6th of 1in).

  PERCENT: SVGUnit = Ellipsis

    Percent, a value that is some fraction of another reference value.

class cairo.PDFMetadata(value: int)

  `PDFMetadata` is used by the `PDFSurface.set_metadata()` method to specify the metadata to set.

  Added in version 1.18.0: Only available with cairo 1.15.10+

  TITLE: PDFMetadata = Ellipsis

    The document title

  AUTHOR: PDFMetadata = Ellipsis

    The document author

  SUBJECT: PDFMetadata = Ellipsis

    The document subject

  KEYWORDS: PDFMetadata = Ellipsis

    The document keywords

  CREATOR: PDFMetadata = Ellipsis

    The document creator

  CREATE_DATE: PDFMetadata = Ellipsis

    The document creation date

  MOD_DATE: PDFMetadata = Ellipsis

    The document modification date

class cairo.ColorMode(value: int)

  Specifies if color fonts are to be rendered using the color glyphs or outline glyphs. Glyphs that do not have a color presentation, and non-color fonts are not affected by this font option.

  Added in version 1.25: Only available with cairo 1.17.8+

  DEFAULT: ColorMode = Ellipsis

    Use the default color mode for font backend and target device.

  NO_COLOR: ColorMode = Ellipsis

    Disable rendering color glyphs. Glyphs are always rendered as outline glyphs

  COLOR: ColorMode = Ellipsis

    Enable rendering color glyphs. If the font contains a color presentation for a glyph, and when supported by the font backend, the glyph will be rendered in color.

class cairo.Dither(value: int)

  Dither is an intentionally applied form of noise used to randomize quantization error, preventing large-scale patterns such as color banding in images (e.g. for gradients). Ordered dithering applies a precomputed threshold matrix to spread the errors smoothly.

  `Dither` is modeled on pixman dithering algorithm choice. As of Pixman 0.40, FAST corresponds to a 8x8 ordered bayer noise and GOOD and BEST use an ordered 64x64 precomputed blue noise.

  Added in version 1.25: Only available with cairo 1.18.0+

  NONE: Dither = Ellipsis

    No dithering.

  DEFAULT: Dither = Ellipsis

    Default choice at cairo compile time. Currently NONE.

  FAST: Dither = Ellipsis

    Fastest dithering algorithm supported by the backend

  GOOD: Dither = Ellipsis

    An algorithm with smoother dithering than FAST

  BEST: Dither = Ellipsis

    Best algorithm available in the backend