Cairo::Context
class Cairo::Context
Cairo context keeps track of everything that verbs affect. It tracks one source, one destination, and one mask. It also tracks several helper variables like your line width and style, your font face and size, and more. Most importantly it tracks the path, which is turned into a mask by drawing verbs.
Represents the main data type (class) for object used when drawing with cairo. To draw with cairo, you create such an object. In Ruby/Gtk you accomplish this by calling Gdk::Drawable#create_cairo_context, method on a drawable object which can be either a Gdk::Window, or a Gdk::Pixmap. (Original GTK API for Gdk::Drawable also listsbitmap, however it fails to identify it sufficiently?)
Before you can start to draw something with cairo, you need to create the cairo context. In Ruby/Gtk you obtain context with Gdk::Drawable#create_cairo_context instance method. Note, you do not supply the source to cairo create method. Instead, you invoke thecreate_cairo_context instance method on a Gdk::Drawable object, which can be either Gdk::Pixmap, or a Gdk::Window. (Original GTK API for Gdk::Drawable also listsbitmap, however, it fails to identify it sufficiently?)
Though in Ruby/Gtk this originally was the only documented method of creating cairo context, that proves to be too limiting, especially when you have to gain access the some Cairo methods not available in Ruby/Gtk Cairo implementation. For that you need torequire 'cairo' module, which is from the Gtk completely separate and independent library. In fact you do not even need to run any particular GUI library, to utilize the power of this 'stand-alone' 2D Cairo Vector Graphics Library. Indeed, since this library does not rely on external graphic interface or Window system, it provides its own mechanisms to create cairo context, which of course must now be bound to some other than your Gtk/Window drawing area or drawing surface. However, currently in Ruby/Gtk, other than active Gtk Window surfaces are not available. This is where the stand-alone Cairo library kicks in. It actually also provides functions (methods) to create such drawing surfaces (see: Ruby Cairo Tutorial, section 12.3.0.2 Running Cairo Code From Non-Gtk Ruby Environment, for hints how to write cairo drawing programs outside of a Gtk graphic window.)
Whether you create a cairo context in Ruby/Gtk or in a non-GUI character based programming environment, it is eventually bound to a drawing surface, which indeed can be some kind of backend, either a file or a GUI window (see: Ruby Cairo Tutorial, section 12.3.0.1.1 Cairo Backends to learn about surfaces Gtk/Cairo environment does not support).
Whatever the target drawing surface is, you use the drawing options on the cairo context, to create shapes with methods like cr.move_to() and cr.line_to(), and then draw shapes with cr.stroke() or cr.fill(), where, indeed, the receiver object"cr",is cairo context created either with the Gdk::Drawable#create_cairo_context method in Gtk/Cairo environment, or by combining a creation of a drawing surface and binding it to to the cairo context created by the rCairo:_:Context.new(surface) method available from in the 'stand-alone' Cairo Graphics Library.
- creating cairo context for rcairo:
-
When you are using stand-alone non-GUI cairo library, you should forget, about Ruby's Gdk::Drawable#create_cairo_context, and resort to plain old Cairo ways of creating it via:
surface = Cairo::XyzSurface.new(width, height) cr = Cairo::Context.new(surface)
by replacing the word "Xyz" above with one of the following { Image, PDF, PS, SVG, ... }.
There are only GDK and Pango related APIs.
Object Hierarchy
- Object
Instance Methods
GDK related APIs
gdk_rectangle(rectangle)
-
Ruby/GDK
Adds the given rectangle to the current path of self.
- rectangle: Gdk::Rectangle
- Returns: self
gdk_region(region)
-
Ruby/GDK
Adds the given region to the current path of self.
- region: Gdk::Region
- Returns: self
set_source_color(color)
-
Ruby/GDK
Sets the specified Gdk::Color as the source color of self.
- color: Gdk::Color
- Returns: self
set_source_pixbuf(pixbuf, pixbuf_x=0, pixbuf_y=0)
-
Ruby/GDK
Sets the given pixbuf as the source pattern for the
Cairo context. The pattern has an extend mode of
Cairo::EXTEND_NONE? and is aligned so that the origin of
pixbuf is pixbuf_x, pixbuf_y
- pixbuf: Gdk::Pixbuf
- pixbuf_x: X coordinate of location to place upper left corner of pixbuf
- pixbuf_y: Y coordinate of location to place upper left corner of pixbuf
- Returns: self
Pango related APIs
create_pango_layout
-
Ruby/Pango Creates a layout object set up to match the current transformation and target surface of the Cairo context. This layout can then be used for text measurement with functions like Pango::Layout#size or drawing with functions like Cairo::Context#show_layout. If you change the transformation or target surface for self, you need to call Cairo::Context#update_layout.
This function is the most convenient way to use Cairo with Pango, however it is slightly inefficient since it creates a separate Pango::Context object for each layout. This might matter in an application that was laying out large amounts of text.
- Returns: the newly created Pango::Layout
pango_glyph_string_path(font, glyphs)
-
Ruby/Pango
Adds the glyphs in glyphs to the current path in self.
The origin of the glyphs (the left
edge of the baseline) will be at the current point of self.
- font: a Pango::Font
- glyphs: a Pango::GlyphString
- Returns: self
pango_layout_path(layout)
-
Ruby/Pango
Adds the text in a Pango::LayoutLine to the current
path in self. The top-left corner of the Pango::Layout
will be at the current point of self.
- layout: a Pango::Layout
- Returns: self
pango_layout_line_path(line)
-
Ruby/Pango
Adds the text in Pango::LayoutLine to the current path
in self. The origin of the glyphs (the left edge of the
line) will be at the current point of self.
- line: a Pango::LayoutLine
- Returns: self
show_pango_glyph_string(font, glyphs)
-
Ruby/Pango
Draws the glyphs in glyphs in self.
The origin of the glyphs (the left edge of the
baseline) will be drawn at the current point of self.
- font: Pango::Font
- glyphs: Pango::GlyphString
- Returns: self
show_pango_layout(layout)
-
Ruby/Pango
Draws a Pango::LayoutLine in self. The
top-left corner of the Pango::Layout will be drawn at
the current point of self.
- layout: a Pango layout
- Returns: self
show_pango_layout_line(line)
-
Ruby/Pango
Draws a Pango::LayoutLine in self. The
origin of the glyphs (the left edge of the line) will be
drawn at the current point of self.
- line: a Pango::LayoutLine
- Returns: self
update_pango_context(context);
-
Ruby/Pango
Updates a Pango::Context previously created for use
with Cairo to match the current transformation and
target surface of a Cairo context. If any layouts have
been created for the context, it's necessary to call
Pango::Layout#context_changed on those layouts.
- context: a Pango::Context, from Pango::CairoFontMap#create_context
- Returns: self
update_pango_layout(layout)
-
Ruby/Pango
Updates the private Pango::Context of a Pango::Layout
created with Cairo::Context#create_layout to match the
current transformation and target surface of a Cairo
context.
- layout: a Pango::Layout, from Cairo::Context#create_layout
- Returns: self
librsvg related API
render_rsvg_handle(handle, id=nil)
-
Ruby/RSVG
Draws a subset of a SVG to a Cairo surface
- handle: a RSVG::Handle.
- id: An element's id within the SVG, or nil to render the whole SVG
Poppler related API
render_poppler_page(page)
-
Ruby/Poppler
Draws a page of a PDF to a cairo surface
- page: a Poppler::Page.
render_poppler_page_selection(page, selection, old_selection, glyph_color, background_color)
-
Ruby/Poppler
Draws a selection in page of a PDF to a cairo surface
- page: a Poppler::Page.
- selection: a Poppler::Rectangle
- old_selection: a Poppler::Rectangle or nil
- glyph_color: a Gdk::Color
- background_color: a Gdk::Color
Keyword(s):
References:[News (2018-06-06 No.1)] [News_20061229_1] [News_20051016_1] [Gdk::Drawable] [Ruby/Pango] [Gtk::PrintContext] [RSVG::Handle] [News (2014-12-27 No.1)] [News (2014-10-12 No.1)] [Cairo::Context] [News (2015-09-13 No.1)] [News (2017-05-30 No.1)] [Poppler::Page] [tut-gtk2-dancr-rbcatut-dwc] [Ruby/GDK] [Pango::Context]