```{index} single: Cairo::Context ``` # Cairo::Context ```{pperl-module-badges} 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`](Context/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`](Context/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`](Context/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`](Context/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`](Context/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`](Context/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`](Context/append_path) Appends a path to the context's current path. #### [`copy_clip_rectangle_list`](Context/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. ```{toctree} :hidden: :maxdepth: 1 Context/select_font_face Context/show_text Context/tag_begin Context/show_glyphs Context/show_text_glyphs Context/copy_path Context/append_path Context/copy_clip_rectangle_list ```