Create Edit FrontPage Index Search Changes History RSS Login

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
- Cairo::Context

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.