Provided by: liblua5.1-oocairo0_1.4-1_amd64

#### Name

```       lua-oocairo-context - Drawing context objects

```

#### Introduction

```       A context object is used to perform all the drawing operations on a Cairo surface.
Context objects can be created by calling the "context_create" function in the module
table returned from "require" and passing in a surface object.

```

#### Methods

```       The following methods are available on context objects:

cr:append_path (path)
Add the path instructions from path to the current path of cr.  The path value should
be an object returned from the "cr:copy_path()" or "cr:copy_path_flat()" method.

cr:arc (cx, cy, radius, angle1, angle2)
Add a curved segment to the current path which approximates a section of a circle
centered at point (cx, cy) with a radius of radius.  The two angles determine which
part of the circle to draw.  They are both measured in radians.  For a complete circle
angle1 should be zero, and angle2 should be 2pi.

-- Draw a complete circle.
local PI = 2 * math.asin(1)
local x, y, radius = 50, 100, 23
cr:arc(x, y, radius, 0, 2 * PI)
cr:stroke()

All five arguments to the method must be numbers.

A straight line will be added to the path from the current point to the start of the
arc, if there is a current point.  To avoid this, call "cr:new_sub_path()" before

cr:arc_negative (cx, cy, radius, angle1, angle2)
Same as "cr:arc()", but goes the opposite way round the circle.

cr:clip ()
From now on clip anything outside the current path, preventing it from being drawn,

cr:clip_extents ()
Returns four numbers in two pairs, the x and y coordinates of the corners of a
rectangle which encloses the area of the surface where drawing can still take place
when clipping is taken in to account.

cr:clip_preserve ()
Same as "cr:clip()" but keeps the current path.

cr:close_path ()
Add a straight line segment to the path from the current point to the point where the
path started from (the first "cr:move_to()" position.

cr:copy_path ()
Returns an object containing details of the instructions which define the current path
on cr at the time this is called, as defined by any calls to methods like
"cr:move_to()" and "cr:line_to()" made so far.  The return value can be passed to
"cr:append_path()".  See lua-oocairo-path(3) for details about what else can be done
with a path object.

cr:copy_path_flat ()
Same as "cr:copy_path()" except that the path returned will not contain any curves.
If there are curves in the current path they will first be converted into a series of
straight lines.

cr:curve_to (c1x, c1y, c2x, c2y, x, y)
Add a curved segment to the current path, from the current point to (x, y), with the
control points (c1x, c1y) and (c2x, c2y).  All six arguments must be numbers.

cr:device_to_user (x, y)
Returns two numbers, the position given by the numbers x and y converted from device
coordinates to user coordinates.

cr:device_to_user_distance (x, y)
Returns two numbers, the distance given by the numbers x and y converted from device
coordinates to user coordinates.

cr:fill ()
Fill in the inside of the current path using colour from the current source.

cr:fill_extents ()
Returns four numbers giving two corners of the rectangular area which would be
affected by a call to "cr:fill()" with the current path.

cr:fill_preserve ()
Same as "cr:fill()" but the current path is left intact for use in further drawing
operations.

cr:font_extents ()
Return a table containing metrics for the currently selected font at its current size,
in user-space coordinates (so not scaled etc. according to the current transformation
matrix).  The table will contain the following entries:

ascent
Distance font extends above baseline.

descent
Distance font extends below baseline.

height
Recommended line height (vertical distance from one baseline to the next).

Largest distance any glyph will advance the text horizontally.

Largest distance any glyph will advance the text vertically.

cr:get_antialias ()
Get the current antialiasing mode, which will be one of the strings accepted by the
"cr:set_antialias()" method.

cr:get_current_point ()
Return two numbers, the coordinates of the current point.  Returns no values if there
is no current point.

cr:get_dash ()
Return two values, a table and a number, which describe the current dash pattern and
offset in the same format as accepted by "cr:set_dash()".

cr:get_fill_rule ()
Return the current fill rule as one of the strings accepted by the
"cr:set_fill_rule()" method.

cr:get_font_face ()
Get the currently selected font face (the unscaled font).  See lua-oocairo-fontface(3)
for details on font face objects.

cr:get_font_matrix ()
Returns the transformation matrix used for the current font.

cr:get_font_options ()
Returns a new font options object containing the options set for font rendering with
this context.  The options won't reflect any defaults provided by the surface, just
the options set with the "cr:set_font_options()" method.

See lua-oocairo-fontopt(3) for more about font options objects.

cr:get_group_target ()
Returns the surface which is currently the destination of drawing operations.  This is
usually the same as "cr:get_target()", except when "cr:push_group()" has created a new
temporary surface.

cr:get_line_cap ()
Returns one of the strings accepted by "cr:set_line_cap()".

cr:get_line_join ()
Returns one of the strings accepted by "cr:set_line_join()".

cr:get_line_width ()
Returns a number, the current line width in pixels.

cr:get_matrix ()
Returns the current transformation matrix as a table of six numbers.

cr:get_miter_limit ()
Returns the current miter limit as a number.

cr:get_operator ()
Returns a string indicating the current compositing operator, as set by the
"cr:set_operator()" method.

cr:get_source ()
Return the pattern object current being used as the source.  See
"lua-oocairo-pattern(3)" for methods available on pattern objects.

cr:get_target ()
Returns the surface on which this context will draw.

cr:get_tolerance ()
Return a single number, as set by "cr:set_tolerance()".

cr:glyph_extents (glyphs)
Same as "cr:text_extents()", but instead of a string, the glyphs value should be table
in the format accepted by "cr:show_glyphs()".

cr:glyph_path (glyphs)
Same as "cr:text_path()", but instead of string takes a table of glyphs like
"cr:show_glyphs()".

cr:has_current_point ()
Returns a boolean value, true if there is a current point (as defined with
"cr:move_to()".

cr:identity_matrix ()
Set the current transformation matrix to the identity matrix, resetting any
transformations which had previously been applied.

cr:in_fill (x, y)
Return a boolean value, true if the coordinates are inside the area which would be
filled by the "cr:fill()" method if it was called with the current path.

cr:in_stroke (x, y)
Return a boolean value, true if the coordinates are inside the area which would be
painted by the "cr:stroke()" method if it was called with the current path and line
drawing options.

cr:line_to (x, y)
Add a straight line segment to the path, from the current point to the coordinates
given.

Both of these set a mask which will be used to filter all drawing.  The parts of the
mask which are transparent will still be drawn, but the opaque parts will not be, and
semitransparent pixels work proportionately.

This method will accept either a pattern object or a surface object, just as for the
"cr:set_source()" method.

The mask only has an alpha channel, so any colour information in the pattern or
surface is ignored.

cr:move_to (x, y)
Set the current point to the coordinates given.

cr:new_path ()

cr:new_sub_path ()
Disconnect from the current path, so anything added to it will form a separate shape.
Mainly used to avoid the extra straight line you get with the "cr:arc()" method.

cr:paint ()
Copy the source to the surface across the whole surface.  This is the same as filling
a rectangle enclosing the whole area of the surface.

cr:paint_with_alpha (alpha)
Same as "cr:paint()" except the source is blended at the proportion given by alpha.
An alpha value of one means complete opacity (same as "cr:paint()"), and zero means
complete transparency (no effect).

cr:path_extents ()
Returns four numbers giving two corners of the rectangular bounding box of the current
path.

cr:pop_group ()
Finish with the temporary surface created by "cr:push_group()" and discard it.

cr:pop_group_to_source ()
Finish with the temporary surface created by "cr:push_group()" and set it as the
source image, as if with a call to "cr:set_source()".

cr:push_group ([content])
Begin drawing on a new temporary surface.  If content is specified then it can limit
what the temporary surface can store.  It should be one of the values accepted by the
"surface_create_similar" function defined in the module table (see lua-oocairo(3)).

cr:rectangle (x, y, width, height)
Add the outline of a rectangle to the current path.  All four arguments must be
numbers.  The rectangle path will be closed at the end.

cr:rel_curve_to (c1x, c1y, c2x, c2y, x, y)
Same as "cr:curve_to()" but with coordinates relative to the current point.

cr:rel_line_to (x, y)
Same as "cr:line_to()" but with coordinates relative to the current point.

cr:rel_move_to (x, y)
Same as "cr:move_to()" but with coordinates relative to the current point.

cr:reset_clip ()
Reset there to be no clipping.

cr:restore ()
Restore the state previously saved with a call to "cr:save()".

cr:rotate (angle)
Apply a rotation to the current transformation matrix, by angle radians.

cr:save ()
Save the current settings for this context on a stack, so that they can be altered and
then restored to their previous state with a call to "cr:restore()".  Multiple saves
and restores can be nested.

cr:scale (sx, sy)
Adjust the current transformation matrix to scale everything by the amount specified
by the numbers sx and sy.

cr:select_font_face (familyname, slant, weight)
Set the font used by methods such as "cr:show_text()" to the font family named by the
string familyname with the specified styling.

The slant and weight values are both optional.

If specified, slant must be one of the following strings:

normal
The default.

italic
oblique

If specified, weight must be one of the following strings:

normal
The default.

bold
cr:set_antialias (antialiastype)
Set the antialiasing mode used for drawing.  The argument must be one of the following
strings:

default
none
gray
subpixel

Additionally, the argument can be one of the Lua boolean values ("true" or "false",
but not "nil"), which will simply turn AA on or off by setting it to "default" or
"none".

cr:set_dash (dashpattern, offset)
Set the dash pattern used for stroking lines.  The dashpattern value must be a table,
which is an array of numbers defining how long each dash or gap should be.  If there
is only one number then it will be treated as if the same number were repeated a
second time.

The offset must be a number giving the distance into the pattern at which the stroke
should start being drawn.

cr:set_fill_rule (fillrule)
Choose the algorithm used for deciding what is inside or outside of a path when
filling its inside.  The argument must be one of the following strings:

winding
even-odd
cr:set_font_face (font)
Set the selected font to the one given, or to the default font if font is nil.  See
lua-oocairo-fontface(3) for details on font face objects.

cr:set_font_matrix (matrix)
Set the transformation matrix used for fonts.  Can be used for rotating text or
slanting the font in unusual ways for example.  The matrix must be a table of six
numbers.

cr:set_font_options (options)
Set the options used for rendering fonts.  The value of options must be a font options
object (see lua-oocairo-fontopt(3)).  The current options can be retrieved with the
"cr:get_font_options()" method.

cr:set_font_size (size)
Set the font size to use for methods like "cr:show_text()".  The size value must be a
number.

cr:set_line_cap (style)
Set the style with which the ends of a path are stroked.  The style value must be one
of the following strings:

butt
Line ends exactly at end point of path.

round
Line is extended in a circle round the end of the path.

square
Line is extended in a square round the end of the path.

cr:set_line_join (style)
Set the style with which corners of a path are stroked.  The style value must be one
of the following strings:

miter
Outside edge of stroke goes straight on to a sharp point.

round
Outside edge of line curves in a circle.

bevel
Outside edge of line is flattened off.

cr:set_line_width (width)
Set the width of lines drawn with the "cr:stroke()" method to the number given, in
pixels.  The default is two pixels wide.

cr:set_matrix (matrix)
Set the current transformation matrix to matrix, which must be a table containing six
numbers.

cr:set_miter_limit (limit)
Set the miter limit to the number given.

cr:set_operator (operator)
Change the operator used for compositing new paint onto what has already been drawn.
The value must be one of the following strings:

atop
clear
dest
dest-atop
dest-in
dest-out
dest-over
in
out
over
This is the default.

saturate
source
xor
cr:set_source (pattern)
cr:set_source (surface, x, y)
Set the source to a ready-made pattern object, or to a surface object with the given
offset.  Setting a pattern object is useful for applying a gradient.  Setting a
surface is useful for drawing the contents of one surface onto another.  The x and y
values indicate what position on surface should be drawn at the origin.

cr:set_source_gdk_color (c, [alpha])
Set the source to a solid colour given by a GdkColor value from the Lua-Gnome library,
and optionally an alpha value using the same range of numbers.  This method is exactly
the same as calling "set_source_rgb" (or "set_source_rgba" if alpha is present),
except that the red, green, and blue components are retrieved from c by treating it as
a table, and all the numbers are treated as 16 bit unsigned integers and scaled to the
range used by Cairo.

If present and not nil, the opacity value alpha must be a number and is expected to
range from 0 for fully transparent to 0xFFFF (65535) for completely opaque.

See the example program gtk-drawing.lua for one use of this method in setting a source
colour and opacity from a GtkColorButton widget.

cr:set_source_pixbuf (pixbuf, x, y)
cr:set_source_pixmap (pixmap, x, y)
Set the source to an image given as a Gdk object.  The value of pixbuf must be a
GdkPixbuf object from the Lua-Gnome library, and that of pixmap must be a GdkPixmap
object.

The x and y coordinates are the same as in "cr:set_source()".

Usually, you'll want to use "set_source_pixbuf", because pixbufs can include
transparency information.

See example program gtk-image.lua for an example of how to use these methods.

cr:set_source_rgb (r, g, b)
Set the source to a solid colour.  The three values must be numbers from zero to one.

cr:set_source_rgba (r, g, b, a)
Set the source to a solid colour with a level of opacity.  The four values must be
numbers from zero to one.  A value of one for a indicates full opacity.

cr:set_tolerance (tolerance)
Set a number which determines how finely curves are spliced up into straight lines
before being drawn.  Higher numbers can increase the quality of the output in some
situations, but will slow down rendering.

cr:show_glyphs (glyphs)
Draw glyphs from a font, but instead of specifying a string of characters, this method
expects the caller to have already worked out which glyphs in the current font to use,
and the exact positions at which they should be placed.  The glyphs value should be a
table containing an array of tables, each of which should contain three numbers:

1.  The index number of the glyph.  The exact meaning of this depends on which font is
selected.

2.  The x coordinate at which to draw the glyph on the surface.

3.  The y coordinate.

cr:show_text (text)
Draw the text given in the string text (which must be encoded as UTF-8), using the
current font face and size, and the current source.  This draws immediately, it
doesn't leave a path for further drawing.  See the "cr:text_path()" method for drawing
outlined text.

cr:show_text_glyphs (text, glyphs, clusters)
Draw the glyphs given by the glyphs table, in the same way as the "cr:show_glyphs()"
method, but if the surface supports it, store the correspondence between the glyphs
and the characters in the UTF-8 string text represented by clusters.

The clusters value must be a table.  It may contain a key called "backward", whose
value will be a boolean value, true if the clusters are listed in reverse order.  It
should also contain an array part containing pairs of values; that is, the clusters
entries with keys starting with the number one should each be a table containing two
numbers, a number of bytes in the text string and a number of glyphs in the glyphs
array, which are meant to correspond to each other.

Only available with Cairo 1.8 or better.

cr:stroke ()
Draw a line along the current path using colour from the current source, with other
settings such line width taken in to account.

cr:stroke_extents ()
Returns four numbers giving two corners of the rectangular area which would be
affected by a call to "cr:stroke()" with the current path.

cr:stroke_preserve ()
Same as "cr:stroke()" but the current path is left intact for use in further drawing
operations.

cr:text_extents (text)
Returns a table of metrics describing the how the text in the string text will appear
when rendered with the current font.  The table will contain the following keys:

x_bearing
y_bearing
Distance from origin to the top left of the box which will be affected by drawing
the text.

width
height
Size of bounding box which will be affected by drawing the text.

Distance the current point will be moved by showing the text.  In other words, the
relative position where the next piece of text should go.

cr:text_path (text)
Set the current path to the outline of the text given in the string text (which should
be encoded as UTF-8), using the glyph shapes from the current font.  This can be used
to draw text with an outline style.

-- Draw some text in a big outlined font, in two
cr:set_font_size(100)
cr:move_to(50, 150)
cr:text_path("Foo!")

-- At this point the path has been set, so we can
-- draw it like any other shape.
cr:set_source_rgb(0.6, 0, 0.3)
cr:fill_preserve()
cr:set_source_rgb(1, 0.7, 1)
cr:stroke()

cr:transform (matrix)
Apply the transformation encoded in matrix, by multiplying the current transformation
matrix by it.

cr:translate (x, y)
Apply a translation transformation, moving the coordinate system by the amount
specified by the two numbers given.

cr:user_to_device (x, y)
Returns two numbers, the position given by the numbers x and y converted from user
coordinates to device coordinates.

cr:user_to_device_distance (x, y)
Returns two numbers, the distance given by the numbers x and y converted from user
coordinates to device coordinates.
```