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

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
           adding the arc.

       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,
           and then discard the path.

       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).

           max_x_advance
               Largest distance any glyph will advance the text horizontally.

           max_y_advance
               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.

       cr:mask (pattern)
       cr:mask (surface, x, y)
           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 ()
           Discard the current 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:

           add
           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.

           x_advance
           y_advance
               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
               -- shades of pink.
               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.