Cairo::Context#
Cairo::Context - the drawing context, cairo’s central object.
A context is made for a surface with Cairo::Context->create($surface) and holds the whole drawing state: the current source, line width, dash pattern, font, transformation matrix, clip region and current path. The drawing operations - fill, stroke, paint, show_text - apply that state to the context’s target surface. save and restore bracket temporary changes to it.
The getters that hand back another object - get_source, get_target, get_group_target, get_font_face, get_scaled_font - return the context’s own object rather than a copy, so changing it changes what the context will draw with. Each keeps itself alive, so it is still usable after the context has gone. get_matrix, get_font_matrix and get_font_options are the exception: those three return a fresh copy that is yours to modify.
Functions#
Other Functions#
create#
Creates a drawing context for $surface and returns it as a Cairo::Context.
status#
Returns the context’s error state as a status name such as 'success' or 'invalid-restore'.
pop_group#
Ends the group started by push_group and returns everything drawn inside it as a pattern.
get_source#
Returns the context’s current source as a Cairo::Pattern subclass matching the kind of source it is.
set_dash#
Sets the dash pattern used by stroke.
get_dash#
Returns the current dash pattern as a flat list, the offset first and the dash lengths after it.
get_matrix#
Returns the context’s current transformation matrix as a Cairo::Matrix.
has_current_point#
Returns true if the current path has a current point, that is, if a relative operation such as rel_line_to has something to start from.
get_current_point#
Returns the current point of the path as the two-element list ($x, $y), in user-space coordinates.
in_clip#
Returns true if the user-space point ($x, $y) is inside the area that the current clip would let drawing through.
select_font_face#
Selects a font by family name for subsequent show_text and text_extents calls.
get_font_matrix#
Returns the context’s current font matrix as a Cairo::Matrix.
get_font_options#
Returns the context’s current font options as a fresh Cairo::FontOptions.
get_scaled_font#
Returns the context’s current scaled font - the font face together with the size and transformation in force - as a Cairo::ScaledFont.
show_text#
Draws $text at the current point using the current font and source, then advances the current point past what was drawn.
text_path#
Adds the outlines of $text to the current path instead of drawing it, so the text can then be filled, stroked or clipped with.
get_font_face#
Returns the context’s current font face as a Cairo::FontFace subclass matching the kind of face it is.
font_extents#
Returns the metrics of the current font as a hash reference with the keys ascent, descent, height, max_x_advance and max_y_advance.
text_extents#
Measures $text in the current font and returns a hash reference with the keys x_bearing, y_bearing, width, height, x_advance and y_advance.
get_target#
Returns the surface the context draws onto, as the concrete Cairo::Surface subclass it really is.
get_group_target#
Returns the surface drawing currently goes to: the innermost group’s surface while a push_group is open, and otherwise the same surface get_target returns.
tag_begin#
Opens a tagged region, used to attach structure such as links and document outlines to PDF output.
tag_end#
Closes the tagged region opened by tag_begin with the same $tag_name.
show_glyphs#
Draws a list of already-positioned glyphs with the current font and source.
glyph_path#
Adds the outlines of a list of positioned glyphs to the current path instead of drawing them, so they can be filled, stroked or clipped with.
glyph_extents#
Measures a list of positioned glyphs and returns a hash reference with the same keys as text_extents: x_bearing, y_bearing, width, height, x_advance and y_advance.
show_text_glyphs#
Draws positioned glyphs while also recording which characters of $text they came from, so that backends such as PDF and SVG can make the result selectable and searchable.
copy_path#
Returns a copy of the current path as a Cairo::Path.
copy_path_flat#
Returns a copy of the current path as a Cairo::Path, with every curve replaced by a chain of line segments.
append_path#
Appends a path to the context’s current path.
copy_clip_rectangle_list#
Returns the current clip region as a plain list of hash references, each with the keys x, y, width and height in user space.