lua-lgi-dev 0.9.0.20151101.git.885af4-1 / usr / share / doc / lua-lgi-dev / docs / cairo.md

# cairo support

Cairo library is an important part of any GTK-based setup, because GTK
internally uses cairo exclusively for painting.  However, cairo itself
is not built using GObject technology and thus imposes quite a problem
for any GObject Introspection based binding, such as lgi.

## Basic binding description

Although internal implementation is a bit different from other fully
introspection-enabled libraries, this difference is not visible to lgi
user.  cairo must be imported in the same way as other libraries, e.g.

    local lgi = require 'lgi'
    local cairo = lgi.cairo

Cairo library itself is organized using object-oriented style, using C
structures as objects (e.g. `cairo_t`, `cairo_surface_t`) and
functions as methods acting upon these objects.  lgi exports objects
as classes in the `cairo` namespace, e.g. `cairo.Context`,
`cairo.Surface` etc.  To create new object instance, cairo offers
assorted `create` methods, e.g. `cairo_create` or
`cairo_pattern_create`, which are mapped as expected to
`cairo.Context.create` and `cairo.Pattern.create`.  It is also
possible to invoke them using lgi's 'constructor' syntax, i.e. to
create new context on specified surface, it is possible to use either
`local cr = cairo.Context.create(surface)` or `local cr =
cairo.Context(surface)`.

### Version checking

`cairo.version` and `cairo.version_string` fields contain current
runtime cairo library version, as returned by their C counterparts
`cairo_version()` and `cairo_version_string()`.  Original
`CAIRO_VERSION_ENCODE` macro is reimplemented as
`cairo.version_encode(major, minor, micro)`.  For example, following
section shows how to guard code which should be run only when cairo
version is at least 1.12:

    if cairo.version >= cairo.version_encode(1, 12, 0) then
       -- Cairo 1.12-specific code
    else
       -- Fallback to older cairo version code
    end

### Synthetic properties

There are many getter and setter functions for assorted cairo objects.
lgi exports them in the form of method calls as the native C interface
does, and it also provides property-like access, so that it is
possible to query or assign named property of the object.  Following
example demonstrates two identical ways to set and get line width on
cairo.Context instance:

    local cr = cairo.Context(surface)
    cr:set_line_width(10)
    print('line width ', cr:get_line_width())

    cr.line_width = 10
    print('line width ', cr.line_width)

In general, any kind of `get_xxx()` method call on any cairo object
can be replaced using `xxx` property on the object, and any
`set_xxx()` method can be replaced by setting `xxx` property.

### cairo.Surface hierarchy

Cairo provides basic rendering surface object `cairo.Surface`, and a
bunch of specialized surfaces implementing rendering to assorted
targets, e.g. `cairo.ImageSurface`, `cairo.PdfSurface` etc.  These
surface provide their own class, which is logically inherited from
`cairo.Surface`.  lgi fully implements this inheritance, so that
calling `cairo.ImageSurface()` actually creates an instance of
`cairo.ImageSurface` class, which provides all methods abd properties
of `cairo.Surface` and and some specialized methods and properties
like `width` and `height`.

In addition, lgi always assigns the real type of the surface, so that
even when `cairo.Context.get_target()` method (or
`cairo.Context.target` property) is designated as returning
`cairo.Surface` instance, upon the call the type of the surface is
queried and proper kind of surface type is really returned.  Following
example demonstrates that it is possible to query
`cairo.ImageSurface`-specific `width` property directly on the
`cairo.Context.target` result.

    -- Assumes the cr is cairo.Context instance with assigned surface
    print('width of the surface' cr.target.width)

It is also possible to use lgi generic typechecking machinery for
checking the type of the surface:

    if cairo.ImageSurface:is_type_of(cr.target) then
	print('width of the surface' cr.target.width)
    else
	print('unsupported type of the surface')
    end

### cairo.Pattern hierarchy

cairo's pattern API actually hides the inheritance of assorted pattern
types.  lgi binding brings this hierarchy up in the same way as for
surfaces described in previous section.  Following hierarchy exists:

    cairo.Pattern
        cairo.SolidPattern
	cairo.SurfacePattern
	cairo.GradientPattern
	    cairo.LinearPattern
	    cairo.RadialPattern
	cairo.MeshPattern

Patterns can be created using static factory methods on
`cairo.Pattern` as documented in cairo documentation.  In addition,
lgi maps creation methods to specific subclass constructors, so
following snippets are equivalent:

    local pattern = cairo.Pattern.create_linear(0, 0, 10, 10)
    local pattern = cairo.LinearPattern(0, 0, 10, 10)

### cairo.Context path iteration

cairo library offers iteration over the drawing path returned via
`cairo.Context.copy_path()` method.  Resulting path can be iterated
using `pairs()` method of `cairo.Path` class.  `pairs()` method
returns iterator suitable to be used in Lua 'generic for' construct.
Iterator returns type of the path element, optionally followed by 0, 1
or 3 points.  Following example shows how to iterate the path.

    local path = cr:copy_path()
    for kind, points in path:pairs() do
       io.write(kind .. ':')
          for pt in ipairs(points) do
             io.write((' { %g, %g }'):format(pt.x, pt.y))
	  end
       end
    end

## Impact of cairo on other libraries

In addition to cairo itself, there is a bunch of cairo-specific
methods inside Gtk, Gdk and Pango libraries.  lgi wires them up so
that they can be called naturally as if they were built in to the
cairo core itself.

### Gdk and Gtk

`Gdk.Rectangle` is just a link to `cairo.RectangleInt` (similar to C,
where `GdkRectangle` is just a typedef of `cairo_rectangle_int_t`).
`gdk_rectangle_union` and `gdk_rectangle_intersect` are wired as a
methods of `Gdk.Rectangle` as expected.

`Gdk.cairo_create()` is aliased as a method
`Gdk.Window.cairo_create()`.  `Gdk.cairo_region_create_from_surface()`
is aliased as `cairo.Region.create_from_surface()`.

`cairo.Context.set_source_rgba()` is overriden so that it also accepts
`Gdk.RGBA` instance as an argument.  Similarly,
`cairo.Context.rectangle()` alternatively accepts `Gdk.Rectangle` as
an argument.

`cairo.Context` has additional methods `get_clip_rectangle()`,
`set_source_color()`, `set_source_pixbuf()`, `set_source_window` and
`region`, implemented as calls to appropriate `Gdk.cairo_xxx`
functions.

Since all these extensions are implemented inside Gdk and Gtk
libraries, they are present only when `lgi.Gdk` is loaded.  When
loading just pure `lgi.cairo`, they are not available.

### PangoCairo

Pango library contains namespace `PangoCairo` which implements a bunch
of cairo-specific helper functions to integrate Pango use with cairo
library.  It is of course possible to call them as global methods of
PangoCairo interface, however lgi override maps the also to methods
and attributes of other classes to which they logically belong.