Index

Package: Cairo

Description

package Cairo is

Bindings to the Cairo 2D graphics library.

The Cairo_Context is the main object used when drawing with cairo. To draw with Cairo, you create a Context, set the target surface, and drawing options for the Cairo_Context, create shapes with functions like Move_To and Line_To, and then draw shapes with Stroke or Fill.

All drawing in Cairo is done on a Cairo_Context.

Drawing on on-screen Gtk widgets should be done in a callback to the "expose" event: When the widget has been created, connect a drawing function:

declare Area : Gtk_Drawing_Area; package Event_Cb is new Gtk.Handlers.Return_Callback (Gtk_Drawing_Area_Record, Boolean); begin Gtk_New (Area); Event_Cb.Connect (Area, "expose_event", Event_Cb.To_Marshaller (Expose_Cb'Access)); end;
In the callback, first get the context of the drawable on which you need to draw, using Gdk.Cairo.Create. Then do the drawing operations, and release the memory allocated to Cr using Cairo.Destroy.

In addition to drawing on on-screen widgets, drawing can also be done using the same Cairo calls to pixbufs (see Gdk.Cairo) to memory (see Cairo.Image_Surface), and to PNG files (see Cairo.Png).

Code samples demonstrating how to use various functionalities of Cairo can be found in the testcairo example, shipped with GtkAda.

Binding from C File version 1.8.8

Types

Cairo_Context 

type Cairo_Context is private;
A Cairo_Context contains the current state of the rendering device, including coordinates of yet to be drawn shapes. Cairo contexts, as Cairo_Context objects are named, are central to cairo and all drawing with cairo is always done to a Cairo_Context object. Memory management of Cairo_Context is done with subprograms Reference and Destroy, see below.

Cairo_Surface 

type Cairo_Surface is private;
A Cairo_Surface represents an image, either as the destination of a drawing operation or as source when drawing onto another surface. To draw to a Cairo_Surface, create a cairo context with the surface as the target, using Create. There are different subtypes of Cairo_Surface for different drawing backends; for example, Cairo.Image_Surface.Create creates a bitmap image in memory. The type of a surface can be queried with Cairo.Surface.Get_Type. Memory management of Cairo_Surface is done with Cairo.Surface.Reference and Cairo.Surface.Destroy.

Cairo_Matrix 

type Cairo_Matrix is record
      Xx : aliased Gdouble;
      Yx : aliased Gdouble;
      Xy : aliased Gdouble;
      Yy : aliased Gdouble;
      X0 : aliased Gdouble;
      Y0 : aliased Gdouble;
   end record;
Xx: Xx component of the affine transformation Yx: Yx component of the affine transformation Xy: Xy component of the affine transformation Yy: Yy component of the affine transformation X0: X translation component of the affine transformation Y0: Y translation component of the affine transformation A Cairo_Matrix holds an affine transformation, such as a scale, rotation, shear, or a combination of those. The transformation of a point (X, Y) is given by: X_New = Xx * X + Xy * Y + X0; Y_New = Yx * X + Yy * Y + Y0;

Cairo_Matrix_Access 

type Cairo_Matrix_Access is access Cairo_Matrix;

Cairo_Pattern 

type Cairo_Pattern is private;
A Cairo_Pattern represents a source when drawing onto a surface. There are different subtypes of Cairo_Pattern, for different types of sources; for example, Cairo.Pattern.Create_Rgb creates a pattern for a solid opaque color. Other than various Cairo.Pattern.Create_<type> functions, some of the pattern types can be implicitly created using various Set_Source_<type> functions; for example Set_Source_Rgb. The type of a pattern can be queried with Cairo.Pattern.Get_Type. Memory management of Cairo_Pattern is done with Cairo.Pattern.Reference and Cairo.Pattern.Destroy.

Cairo_Destroy_Func 

type Cairo_Destroy_Func is access procedure (Arg1 : System.Address);
Data: The Data element being destroyed. Cairo_destroy_func the type of function which is called when a data element is destroyed. It is passed the pointer to the data element and should free any memory and resources allocated for it.

Cairo_User_Data_Key 

type Cairo_User_Data_Key is record
      Unused : aliased Gint;
   end record;
Unused: not used; ignore. Cairo_User_Data_Key is used for attaching user data to cairo data structures. The actual contents of the struct is never used, and there is no need to initialize the object; only the unique address of a Cairo_User_Data_Key object is used. Typically, you would just use the address of a static Cairo_User_Data_Key object.

Cairo_Status 

type Cairo_Status is
     (
      Cairo_Status_Success,
      --  no error has occurred

      Cairo_Status_No_Memory,
      --  out of memory

      Cairo_Status_Invalid_Restore,
      --  Cairo_Restore called without matching Cairo_Save

      Cairo_Status_Invalid_Pop_Group,
      --  no saved group to pop

      Cairo_Status_No_Current_Point,
      --  no current point defined

      Cairo_Status_Invalid_Matrix,
      --  invalid matrix (not invertible)

      Cairo_Status_Invalid_Status,
      --  invalid value for an input Cairo_status

      Cairo_Status_Null_Pointer,
      --  NULL pointer

      Cairo_Status_Invalid_String,
      --  input string not valid UTF-8

      Cairo_Status_Invalid_Path_Data,
      --  input path data not valid

      Cairo_Status_Read_Error,
      --  error while reading from input stream

      Cairo_Status_Write_Error,
      --  error while writing to output stream

      Cairo_Status_Surface_Finished,
      --  target surface has been finished

      Cairo_Status_Surface_Type_Mismatch,
      --  the surface type is not appropriate for the operation

      Cairo_Status_Pattern_Type_Mismatch,
      --  the pattern type is not appropriate for the operation

      Cairo_Status_Invalid_Content,
      --  invalid value for an input Cairo_content

      Cairo_Status_Invalid_Format,
      --  invalid value for an input Cairo_format

      Cairo_Status_Invalid_Visual,
      --  invalid value for an input Visual*

      Cairo_Status_File_Not_Found,
      --  file not found

      Cairo_Status_Invalid_Dash,
      --  invalid value for a dash setting

      Cairo_Status_Invalid_Dsc_Comment,
      --  invalid value for a DSC comment (Since 1.2)

      Cairo_Status_Invalid_Index,
      --  invalid index passed to getter (Since 1.4)

      Cairo_Status_Clip_Not_Representable,
      --  clip region not representable in desired format (Since 1.4)

      Cairo_Status_Temp_File_Error,
      --  error creating or writing to a temporary file (Since 1.6)

      Cairo_Status_Invalid_Stride,
      --  invalid value for stride (Since 1.6)

      Cairo_Status_Font_Type_Mismatch,
      --  the font type is not appropriate for the operation (Since 1.8)

      Cairo_Status_User_Font_Immutable,
      --  the user-font is immutable (Since 1.8)

      Cairo_Status_User_Font_Error,
      --  error occurred in a user-font callback function (Since 1.8)

      Cairo_Status_Negative_Count,
      --  negative number used where it is not allowed (Since 1.8)

      Cairo_Status_Invalid_Clusters,
      --  input clusters do not represent the accompanying text and glyph
      --  array (Since 1.8)

      Cairo_Status_Invalid_Slant,
      --  invalid value for an input Cairo_Font_Slant (Since 1.8)

      Cairo_Status_Invalid_Weight
      --  invalid value for an input Cairo_Font_Weight (Since 1.8)
     );
Cairo_Status is used to indicate errors that can occur when using Cairo. In some cases it is returned directly by functions. but when using Cairo_T, the last error, if any, is stored in the context and can be retrieved with Cairo_Status. New entries may be added in future versions. Use Cairo_Status_To_String to get a human-readable representation of an error message.

Cairo_Content 

subtype Cairo_Content is Guint;
Cairo_content is used to describe the content that a surface will contain, whether color information, alpha information (translucence vs. opacity), or both. Note: The large values here are designed to keep Cairo_Content values distinct from Cairo_Format values so that the implementation can detect the error if users confuse the two types.

Cairo_Operator 

type Cairo_Operator is
     (Cairo_Operator_Clear,
      --  clear destination layer (bounded)

      Cairo_Operator_Source,
      --  replace destination layer (bounded)

      Cairo_Operator_Over,
      --  draw source layer on top of destination layer (bounded)

      Cairo_Operator_In,
      --  draw source where there was destination content (unbounded)

      Cairo_Operator_Out,
      --  draw source where there was no destination content (unbounded)

      Cairo_Operator_Atop,
      --  draw source on top of destination content and only there

      Cairo_Operator_Dest,
      --  ignore the source

      Cairo_Operator_Dest_Over,
      --  draw destination on top of source

      Cairo_Operator_Dest_In,
      --  leave destination only where there was source content (unbounded)

      Cairo_Operator_Dest_Out,
      --  leave destination only where there was no source content

      Cairo_Operator_Dest_Atop,
      --  leave destination on top of source content and only there (unbounded)

      Cairo_Operator_Xor,
      --  source and destination are shown where there is only one of them

      Cairo_Operator_Add,
      --  source and destination layers are accumulated

      Cairo_Operator_Saturate
      --  like over, but assuming source and dest are disjoint geometries
     );
Cairo_operator is used to set the compositing operator for all cairo drawing operations. The default operator is Cairo_Operator_Over. The operators marked as "unbounded" modify their destination even outside of the mask layer (that is, their effect is not bound by the mask layer). However, their effect can still be limited by way of clipping. To keep things simple, the operator descriptions here document the behavior for when both source and destination are either fully transparent or fully opaque. The actual implementation works for translucent layers too. For a more detailed explanation of the effects of each operator, including the mathematical definitions, see http://cairographics.org/operators/

Cairo_Antialias 

type Cairo_Antialias is
     (
      Cairo_Antialias_Default,
      --  Use the default antialiasing for the subsystem and target device

      Cairo_Antialias_None,
      --  Use a bilevel alpha mask

      Cairo_Antialias_Gray,
      --  Perform single-color antialiasing (using shades of gray for black
      --  text on a white background, for example).

      Cairo_Antialias_Subpixel
      --  Perform antialiasing by taking advantage of the order of subpixel
      --  elements on devices such as LCD panels
     );
Specifies the type of antialiasing to do when rendering text or shapes.

Cairo_Fill_Rule 

type Cairo_Fill_Rule is
     (Cairo_Fill_Rule_Winding,
      --  If the path crosses the ray from left-to-right, counts +1. If the
      --  path crosses the ray from right to left, counts -1. (Left and right
      --  are determined from the perspective of looking along the ray from
      --  the starting point). If the total count is non-zero, the point will
      --  be filled.

      Cairo_Fill_Rule_Even_Odd
      --  Counts the total number of
      --  intersections, without regard to the orientation of the contour. If
      --  the total number of intersections is odd, the point will be filled.
     );
Cairo_Fill_Rule is used to select how paths are filled. For both fill rules, whether or not a point is included in the fill is determined by taking a ray from that point to infinity and looking at intersections with the path. The ray can be in any direction, as long as it doesn't pass through the end point of a segment or have a tricky intersection such as intersecting tangent to the path. (Note that filling is not actually implemented in this way. This is just a description of the rule that is applied.) The default fill rule is Cairo_Fill_Rule_Winding. New entries may be added in future versions.

Cairo_Line_Cap 

type Cairo_Line_Cap is
     (Cairo_Line_Cap_Butt,
      --  start(stop) the line exactly at the start(end) point

      Cairo_Line_Cap_Round,
      --  use a round ending, the center of the circle is the end point

      Cairo_Line_Cap_Square
      --  use squared ending, the center of the square is the end point
     );

Cairo_Line_Join 

type Cairo_Line_Join is
     (Cairo_Line_Join_Miter,
      --  use a sharp (angled) corner, see Set_Miter_Limit

      Cairo_Line_Join_Round,
      --  use a rounded join, the center of the circle is the joint point

      Cairo_Line_Join_Bevel
      --  use a cut-off join, the join is cut off at half the line width from
      --  the joint point
     );

Dash_Array 

type Dash_Array is array (Natural range <>) of Gdouble;

Cairo_Bool 

type Cairo_Bool is new Boolean;

Cairo_Rectangle 

type Cairo_Rectangle is record
      X      : aliased Gdouble;
      Y      : aliased Gdouble;
      Width  : aliased Gdouble;
      Height : aliased Gdouble;
   end record;
X: X coordinate of the left side of the rectangle Y: Y coordinate of the the top side of the rectangle Width: Width of the rectangle Height: Height of the rectangle A data structure for holding a rectangle. Since: 1.4

Cairo_Rectangle_Array 

type Cairo_Rectangle_Array is array (Natural) of Cairo_Rectangle;

Cairo_Rectangle_Array_Access 

type Cairo_Rectangle_Array_Access is access all Cairo_Rectangle_Array;

Cairo_Rectangle_List 

type Cairo_Rectangle_List is record
      Status         : aliased Cairo_Status;
      Rectangles     : Cairo_Rectangle_Array_Access;
      --  Warning: for efficiency reasons, Rectangles is a direct mapping to
      --  the C structure. Therefore, there is no bounds checking on this
      --  array, user needs to make sure only to access data between indexes 0
      --  and Num_Rectanges-1.
      Num_Rectangles : aliased Gint;
   end record;
Status: Error Status of the rectangle list Rectangles: Array containing the Rectangles Num_Rectangles: Number of rectangles in this list A data structure for holding a Dynamically allocated array of rectangles. Since: 1.4

Cairo_Rectangle_List_Access 

type Cairo_Rectangle_List_Access is access all Cairo_Rectangle_List;

Cairo_Scaled_Font 

type Cairo_Scaled_Font is private;
A Cairo_Scaled_Font is a font scaled to a particular size and device resolution. A Cairo_Scaled_Font is most useful for low-level font usage where a library or application wants to cache a reference to a scaled font to speed up the computation of metrics. There are various types of scaled fonts, depending on the font backend they use. The type of a scaled font can be queried using Cairo.Scaled_Font.Get_Type. Memory management of Cairo_Scaled_Font is done with Cairo.Scaled_Font.Reference and Cairo.Scaled_Font.Destroy.

Cairo_Font_Face 

type Cairo_Font_Face is private;
A Cairo_Font_Face specifies all aspects of a font other than the size or font matrix (a font matrix is used to distort a font by sheering it or scaling it unequally in the two directions) . A font face can be set on a Cairo_Context by using Set_Font_Face; the size and font matrix are set with Set_Font_Size and Set_Font_Matrix. There are various types of font faces, depending on the font backend they use. The type of a font face can be queried using Cairo.Font_Face.Get_Type. Memory management of Cairo_Font_Face is done with Cairo.Font_Face.Reference and Cairo.Font_Face.Destroy. The Cairo_glyph structure holds information about a single glyph when drawing or measuring text. A font is (in simple terms) a collection of shapes used to draw text. A glyph is one of these shapes. There can be multiple glyphs for a single character (alternates to be used in different contexts, for example), or a glyph can be a ligature of multiple characters. Cairo doesn't expose any way of converting input text into glyphs, so in order to use the Cairo interfaces that take arrays of glyphs, you must directly access the appropriate underlying font system. Note that the offsets given by X and Y are not cumulative. When drawing or measuring text, each glyph is individually positioned with respect to the overall origin

Cairo_Glyph 

type Cairo_Glyph is record
      Index : aliased Gulong;
      --  Glyph Index in the font. The exact interpretation of the
      --  glyph index depends on the font technology being used.

      X     : aliased Gdouble;
      --  The offset in the X direction between the origin used for
      --  drawing or measuring the string and the origin of this glyph.

      Y     : aliased Gdouble;
      --  The offset in the Y direction between the origin used for drawing or
      --  measuring the string and the origin of this glyph.
   end record;
A Cairo_Font_Face specifies all aspects of a font other than the size or font matrix (a font matrix is used to distort a font by sheering it or scaling it unequally in the two directions) . A font face can be set on a Cairo_Context by using Set_Font_Face; the size and font matrix are set with Set_Font_Size and Set_Font_Matrix. There are various types of font faces, depending on the font backend they use. The type of a font face can be queried using Cairo.Font_Face.Get_Type. Memory management of Cairo_Font_Face is done with Cairo.Font_Face.Reference and Cairo.Font_Face.Destroy. The Cairo_glyph structure holds information about a single glyph when drawing or measuring text. A font is (in simple terms) a collection of shapes used to draw text. A glyph is one of these shapes. There can be multiple glyphs for a single character (alternates to be used in different contexts, for example), or a glyph can be a ligature of multiple characters. Cairo doesn't expose any way of converting input text into glyphs, so in order to use the Cairo interfaces that take arrays of glyphs, you must directly access the appropriate underlying font system. Note that the offsets given by X and Y are not cumulative. When drawing or measuring text, each glyph is individually positioned with respect to the overall origin

Cairo_Text_Cluster 

type Cairo_Text_Cluster is record
      Num_Bytes  : aliased Gint;
      --  The number of bytes of UTF-8 text covered by cluster

      Num_Glyphs : aliased Gint;
      --  The number of glyphs covered by cluster
   end record;
The Cairo_text_cluster structure holds information about a single text cluster. A text cluster is a minimal mapping of some glyphs corresponding to some UTF-8 text. For a cluster to be valid, both num_bytes and num_glyphs should be non-negative, and at least one should be non-zero. Note that clusters with zero glyphs are not as well supported as normal clusters. For example, PDF rendering applications typically ignore those clusters when PDF text is being selected. See Show_Text_Glyphs for how clusters are used in advanced text operations. Since: 1.8

Cairo_Text_Cluster_Flags 

subtype Cairo_Text_Cluster_Flags is Guint;
Specifies properties of a text cluster mapping. Since: 1.8

Cairo_Text_Extents 

type Cairo_Text_Extents is record
      X_Bearing : aliased Gdouble;
      --  The horizontal distance from the origin to the
      --  leftmost part of the glyphs as drawn. Positive if the
      --  glyphs lie entirely to the right of the origin.

      Y_Bearing : aliased Gdouble;
      --  The vertical distance from the origin to the
      --  topmost part of the glyphs as drawn. Positive only if the
      --  glyphs lie completely below the origin; will usually be
      --  negative.

      Width     : aliased Gdouble;
      --  Width of the glyphs as drawn

      Height    : aliased Gdouble;
      --  Height of the glyphs as drawn

      X_Advance : aliased Gdouble;
      --  Distance to advance in the X direction after drawing these glyphs

      Y_Advance : aliased Gdouble;
      --  Distance to advance in the Y direction
      --  after drawing these glyphs. Will typically be zero except
      --  for vertical text layout as found in East-Asian languages.
   end record;
The Cairo_text_extents structure stores the extents of a single glyph or a string of glyphs in user-space coordinates. Because text extents are in user-space coordinates, they are mostly, but not entirely, independent of the current transformation matrix. If you call Scale (Cr, 2.0, 2.0), text will be drawn twice as big, but the reported text extents will not be doubled. They will change slightly due to hinting (so you can't assume that metrics are independent of the transformation matrix), but otherwise will remain unchanged.

Cairo_Font_Extents 

type Cairo_Font_Extents is record
      Ascent        : aliased Gdouble;
      --  The distance that the font extends above the baseline.
      --  Note that this is not always exactly equal to the maximum
      --  of the extents of all the glyphs in the font, but rather
      --  is picked to express the font designer's intent as to
      --  how the font should align with elements above it.

      Descent       : aliased Gdouble;
      --  The distance that the font extends below the baseline.
      --  This value is positive for typical fonts that include
      --  portions below the baseline. Note that this is not always
      --  exactly equal to the maximum of the extents of all the
      --  glyphs in the font, but rather is picked to express the
      --  font designer's intent as to how the the font should
      --  align with elements below it.

      Height        : aliased Gdouble;
      --  The recommended vertical distance between baselines when
      --  setting consecutive lines of text with the font. This
      --  is greater than ascent+descent by a
      --  quantity known as the line spacing or external leading. When space is
      --  at a premium, most fonts can be set with only a distance of
      --  ascent+descent between lines.

      Max_X_Advance : aliased Gdouble;
      --  The maximum distance in the X direction that
      --  the the origin is advanced for any glyph in the font.

      Max_Y_Advance : aliased Gdouble;
      --  The maximum distance in the Y direction that
      --  the the origin is advanced for any glyph in the font.
      --  this will be zero for normal fonts used for horizontal
      --  writing. (The scripts of East Asia are sometimes written
      --  vertically.)
   end record;
The Cairo_font_extents structure stores metric information for a font. Values are given in the current user-space coordinate system. Because font metrics are in user-space coordinates, they are mostly, but not entirely, independent of the current transformation matrix. If you call Scale (Cr, 2.0, 2.0), text will be drawn twice as big, but the reported text extents will not be doubled. They will change slightly due to hinting (so you can't assume that metrics are independent of the transformation matrix), but otherwise will remain unchanged.

Cairo_Font_Slant 

type Cairo_Font_Slant is (
                             Cairo_Font_Slant_Normal,
                             Cairo_Font_Slant_Italic,
                             Cairo_Font_Slant_Oblique);
Specifies variants of a font face based on their slant.

Cairo_Font_Weight 

type Cairo_Font_Weight is (
                              Cairo_Font_Weight_Normal,
                              Cairo_Font_Weight_Bold);
Specifies variants of a font face based on their weight.

Cairo_Subpixel_Order 

type Cairo_Subpixel_Order is
     (Cairo_Subpixel_Order_Default,
      --  Use the default subpixel order for the target device

      Cairo_Subpixel_Order_Rgb,
      --  Subpixel elements are arranged horizontally with red at the left

      Cairo_Subpixel_Order_Bgr,
      --  Subpixel elements are arranged horizontally with blue at the left

      Cairo_Subpixel_Order_Vrgb,
      --  Subpixel elements are arranged vertically with red at the top

      Cairo_Subpixel_Order_Vbgr
      --  Subpixel elements are arranged vertically with blue at the top
     );

Cairo_Hint_Style 

type Cairo_Hint_Style is
     (Cairo_Hint_Style_Default,
      --  Use the default hint style for font backend and target device

      Cairo_Hint_Style_None,
      --  Do not hint outlines

      Cairo_Hint_Style_Slight,
      --  Hint outlines slightly to improve contrast while retaining good
      --  fidelity to the original shapes.

      Cairo_Hint_Style_Medium,
      --  Hint outlines with medium strength giving a compromise between
      --  fidelity to the original shapes and contrast

      Cairo_Hint_Style_Full
      --  Hint outlines to maximize contrast
     );

Cairo_Hint_Metrics 

type Cairo_Hint_Metrics is
     (Cairo_Hint_Metrics_Default,
      --  Hint metrics in the default manner for the font backend and target
      --  device

      Cairo_Hint_Metrics_Off,
      --  Do not hint font metrics

      Cairo_Hint_Metrics_On
      --  Hint font metrics
     );

Cairo_Font_Options 

type Cairo_Font_Options is private;
An opaque structure holding all options that are used when rendering fonts. Individual features of a Cairo_Font_Options can be set or accessed using functions named Cairo.Font_Options.Set_<feature_Name> and Cairo.Font_Options.Get_<feature_Name>, like Cairo.Font_Options.Set_Antialias and Cairo.Font_Options.Get_Antialias. New features may be added to a Cairo_font_options in the future. For this reason, Cairo.Font_Options.Copy, Cairo.Font_Options.Equal, Cairo.Font_Options.Merge, and Cairo.Font_Options.Hash should be used to copy, check for equality, merge, or compute a hash value of Cairo_Font_Options objects.

Cairo_Font_Type 

type Cairo_Font_Type is
     (Cairo_Font_Type_Toy,
      --  The font was created using cairo's toy font api (Since: 1.8)

      Cairo_Font_Type_Ft,
      --  The font is of type FreeType

      Cairo_Font_Type_Win32,
      --  The font is of type Win32

      Cairo_Font_Type_Quartz,
      --  The font is of type Quartz (Since: 1.6)

      Cairo_Font_Type_User
      --  The font was create using cairo's user font api
     );

Dash_Array_Access 

type Dash_Array_Access is access all Dash_Array;

Cairo_Path_Data_Type 

type Cairo_Path_Data_Type is
     (Cairo_Path_Move_To,    --  A move-to operation
      Cairo_Path_Line_To,    --  A line-to operation
      Cairo_Path_Curve_To,   --  A curve-to operation
      Cairo_Path_Close_Path  --  A close-path operation
     );

Header_Type 

type Header_Type is record
      Path_Type : aliased Cairo_Path_Data_Type;
      Length    : aliased Gint;
   end record;
A Path header. See Cairo_Path_Data for details.

Point_Type 

type Point_Type is record
      X : aliased Gdouble;
      Y : aliased Gdouble;
   end record;
A geometrical point. See Cairo_Path_Data for details.

Cairo_Path_Data 

type Cairo_Path_Data (Discr : Guint := 0) is record
      case Discr is
         when 0 =>
            Header : aliased Header_Type;
         when others =>
            Point : aliased Point_Type;
      end case;
   end record;
Cairo_path_data is used to represent the path data inside a Cairo_path. The data structure is designed to try to balance the demands of efficiency and ease-of-use. A path is represented as an array of Cairo_Path_Data, which is a union of headers and points. Each portion of the path is represented by one or more elements in the array, (one header followed by 0 or more points). The length value of the header is the number of array elements for the current portion including the header, (ie. length == 1 + of points), and where the number of points for each element type is as follows: Cairo_Path_Move_To: 1 point Cairo_Path_Line_To: 1 point Cairo_Path_Curve_To: 3 points Cairo_Path_Close_Path: 0 points The semantics and ordering of the coordinate values are consistent with Move_To, Line_To, Curve_To, and Close_Path. Here is sample code for iterating through a Cairo_Path: declare J : Gint; Path : Cairo_Path; Data : Cairo_Path_Data; begin Path = Copy_Path (Cr); J := 0; while J < Path.Num_Data loop Data := Path.Data(J); case Data.Header.Path_Type is when Cairo_Path_Move_To => Do_Move_To_Things (Data(1).Point.X, Data(1).Point.Y); when Cairo_Path_Line_To => Do_Line_To_Things (Data(1).Point.X, Data(1).Point.Y); when Cairo_Path_Curve_To => Do_Curve_To_Things (Data(1).Point.X, Data(1).Point.Y, Data(2).Point.X, Data(2).Point.Y, Data(3).Point.X, Data(3).Point.Y); when Cairo_Path_Curve_To => Do_Close_Path_Things; end case; J := J + Path.Data[J].Header.Length; end loop; Path_Destroy (Path); end; As of cairo 1.4, cairo does not mind if there are more elements in a portion of the path than needed. Such elements can be used by users of the cairo API to hold extra values in the path data structure. For this reason, it is recommended that applications always use Data.Header.Length to iterate over the path data, instead of hardcoding the number of elements for each element type.

Path_Data_Array 

type Path_Data_Array is array (Natural) of Cairo_Path_Data;

Path_Data_Array_Access 

type Path_Data_Array_Access is access all Path_Data_Array;

Cairo_Path 

type Cairo_Path is record
      Status   : aliased Cairo_Status;
      Data     : Path_Data_Array_Access;
      --  Warning: for efficiency reasons, Data is a direct mapping to the C
      --  structure. Therefore, there is no bounds checking on this array,
      --  the user needs to make sure only to access data between indexes
      --  0 and Num_Data-1.
      Num_Data : aliased Gint;
   end record;

Cairo_Path_Access 

type Cairo_Path_Access is access all Cairo_Path;
Status: the current error Status Data: the elements in the path Num_Data: the number of elements in the data array A data structure for holding a path. This data structure serves as the return value for Copy_Path and Copy_Path_Flat as well the input value for Append_Path. See Cairo_Path_Data for hints on how to iterate over the actual data within the path. The num_data member gives the number of elements in the data array. This number is larger than the number of independent path portions (defined in Cairo_Path_Data_Type), since the data includes both headers and coordinates for each portion.

Constants & Global variables

Cairo_Content_Color (Cairo_Content) 

Cairo_Content_Color       : constant Cairo_Content := 4096;
The surface will hold color content only.

Cairo_Content_Alpha (Cairo_Content) 

Cairo_Content_Alpha       : constant Cairo_Content := 8192;
CAIRO_CONTENT_ALPHA: The surface will hold alpha content only.

Cairo_Content_Color_Alpha (Cairo_Content) 

Cairo_Content_Color_Alpha : constant Cairo_Content := 12288;
CAIRO_CONTENT_COLOR_ALPHA: The surface will hold color and alpha content.

No_Dashes (Dash_Array) 

No_Dashes : constant Dash_Array (1 .. 0) := (others => 0.0);

Cairo_Text_Cluster_Flag_Backward (Cairo_Text_Cluster_Flags) 

Cairo_Text_Cluster_Flag_Backward : constant Cairo_Text_Cluster_Flags := 1;
The clusters in the cluster array map to glyphs in the glyph array from end to start.

Null_Context (Cairo_Context) 

Null_Context      : constant Cairo_Context;

Null_Surface (Cairo_Surface) 

Null_Surface      : constant Cairo_Surface;

Null_Pattern (Cairo_Pattern) 

Null_Pattern      : constant Cairo_Pattern;

Null_Scaled_Font (Cairo_Scaled_Font) 

Null_Scaled_Font  : constant Cairo_Scaled_Font;

Null_Font_Face (Cairo_Font_Face) 

Null_Font_Face    : constant Cairo_Font_Face;

Null_Font_Options (Cairo_Font_Options) 

Null_Font_Options : constant Cairo_Font_Options;

Subprograms & Entries

Unchecked_Free 

procedure Unchecked_Free is new Ada.Unchecked_Deallocation 
(Cairo_Matrix, Cairo_Matrix_Access);

Create 

function Create 
(Target: Cairo_Surface) return Cairo_Context;
Target: Target surface for the context Creates a new Cairo_Context with all graphics state parameters set to default values and with target as a target surface. The target surface should be constructed with a backend-specific function such as Cairo.Image_Surface.Create. This function references target, so you can immediately call Cairo.Surface.Destroy on it if you don't need to maintain a separate reference to it. Return value: a newly allocated Cairo_Context with a reference count of 1. The initial reference count should be released with Destroy when you are done using the Cairo_Context. This function never returns NULL. If memory cannot be allocated, a special Cairo_Context object will be returned on which Status returns Cairo_Status_No_Memory. You can use this object normally, but no drawing will be done.

Reference 

function Reference 
(Cr: Cairo_Context) return Cairo_Context;
Cr: a Cairo_Context Increases the reference count on cr by one. This prevents cr from being destroyed until a matching call to Destroy is made. The number of references to a Cairo_Context can be retrieved using Get_Reference_Count. Return value: the referenced Cairo_Context.

Destroy 

procedure Destroy 
(Cr: Cairo_Context);
Cr: a Cairo_Context Decreases the reference count on cr by one. If the result is zero, then cr and all associated resources are freed. See Reference.

Get_Reference_Count 

function Get_Reference_Count 
(Cr: Cairo_Context) return Guint;
Cr: a Cairo_Context Returns the current reference count of cr. Return value: the current reference count of cr. If the object is a nil object, 0 will be returned. Since: 1.4

Get_User_Data 

function Get_User_Data 
(Cr: Cairo_Context;
Key: access Cairo_User_Data_Key) return System.Address;
Cr: a Cairo_Context Key: the address of the Cairo_User_Data_Key the user data was attached to Return user data previously attached to cr using the specified key. If no user data has been attached with the given key this function returns NULL. Return value: the user data previously attached or NULL. Since: 1.4

Set_User_Data 

function Set_User_Data 
(Cr: Cairo_Context;
Key: access Cairo_User_Data_Key;
User_Data: System.Address;
Destroy: Cairo_Destroy_Func) return      Cairo_Status;
Cr: a Cairo_Context Key: the address of a Cairo_User_Data_Key to attach the user data to User_Data: the user data to attach to the Cairo_Context Destroy: a Cairo_Destroy_Func which will be called when the Cairo_Context is destroyed or when new user data is attached using the same key. Attach user data to cr. To remove user data from a surface, call this function with the key that was used to set it and NULL for data. Return value: CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY if a slot could not be allocated for the user data. Since: 1.4

Save 

procedure Save 
(Cr: Cairo_Context);
Cr: a Cairo_Context Makes a copy of the current state of cr and saves it on an internal stack of saved states for cr. When Cairo_Restore is called, cr will be restored to the saved state. Multiple calls to Cairo_Save and Cairo_Restore can be nested; each call to Cairo_Restore restores the state from the matching paired Cairo_Save. It isn't necessary to clear all saved states before a Cairo_Context is freed. If the reference count of a Cairo_Context drops to zero in response to a call to Cairo_Destroy, any saved states will be freed along with the Cairo_Context.

Restore 

procedure Restore 
(Cr: Cairo_Context);
Cr: a Cairo_Context Restores cr to the state saved by a preceding call to Cairo_Save and removes that state from the stack of saved states.

Push_Group 

procedure Push_Group 
(Cr: Cairo_Context);
Cr: a cairo context Temporarily redirects drawing to an intermediate surface known as a group. The redirection lasts until the group is completed by a call to Pop_Group or Pop_Group_To_Source. These calls provide the result of any drawing to the group as a pattern, (either as an explicit object, or set as the source pattern). This group functionality can be convenient for performing intermediate compositing. One common use of a group is to render objects as opaque within the group, (so that they occlude each other), and then blend the result with translucence onto the destination. Groups can be nested arbitrarily deep by making balanced calls to Push_Group/Pop_Group. Each call pushes/pops the new target group onto/from a stack. The Push_Group function calls Save so that any changes to the graphics state will not be visible outside the group, (the pop_group functions call Restore). By default the intermediate group will have a content type of Cairo_Content_Color_Alphe. Other content types can be chosen for the group by using Push_Group_With_Content instead. As an example, here is how one might fill and stroke a path with translucence, but without any portion of the fill being visible under the stroke: Push_Group (Cr); Set_Source (Cr, Fill_Pattern); Fill_Preserve (Cr); Set_Source (Cr, Stroke_Pattern); Stroke (Cr); Pop_Group_To_Source (Cr); Paint_With_Alpha (Cr, Alpha); Since: 1.2

Push_Group_With_Content 

procedure Push_Group_With_Content 
(Cr: Cairo_Context;
Content: Cairo_Content);
Cr: a cairo context Content: a Cairo_Content indicating the type of group that will be created Temporarily redirects drawing to an intermediate surface known as a group. The redirection lasts until the group is completed by a call to Pop_Group or Pop_Group_To_Source. These calls provide the result of any drawing to the group as a pattern, (either as an explicit object, or set as the source pattern). The group will have a content type of content. The ability to control this content type is the only distinction between this function and Push_Group which you should see for a more detailed description of group rendering. Since: 1.2

Pop_Group 

function Pop_Group 
(Cr: Cairo_Context) return Cairo_Pattern;
Cr: a cairo context Terminates the redirection begun by a call to Push_Group or Push_Group_With_Content and returns a new pattern containing the results of all drawing operations performed to the group. The Pop_Group function calls Restore, (balancing a call to Save by the Push_Group function), so that any changes to the graphics state will not be visible outside the group. Return value: a newly created (surface) pattern containing the results of all drawing operations performed to the group. The caller owns the returned object and should call Cairo.Pattern.Destroy when finished with it. Since: 1.2

Pop_Group_To_Source 

procedure Pop_Group_To_Source 
(Cr: Cairo_Context);
Cr: a cairo context Terminates the redirection begun by a call to Push_Group or Push_Group_With_Content and installs the resulting pattern as the source pattern in the given cairo context. The behavior of this function is equivalent to the sequence of operations: declare Group: Cairo_Pattern := Pop_Group (Cr); begin Set_Source (Cr, Group); Cairo.Pattern.Destroy (Group); end; but is more convenient as their is no need for a variable to store the short-lived pointer to the pattern. The Pop_Group function calls Restore, (balancing a call to Save by the push_group function), so that any changes to the graphics state will not be visible outside the group. Since: 1.2

Set_Operator 

procedure Set_Operator 
(Cr: Cairo_Context;
Op: Cairo_Operator);
Cr: a Cairo_Context Op: a compositing Operator, specified as a Cairo_Operator Sets the compositing operator to be used for all drawing operations. See Cairo_Operator for details on the semantics of each available compositing operator. The default operator is Cairo_Operator_Over.

Set_Source 

procedure Set_Source 
(Cr: Cairo_Context;
Source: Cairo_Pattern);
Cr: a cairo context Source: a Cairo_Pattern to be used as the Source for subsequent drawing operations. Sets the source pattern within Cr to source. This pattern will then be used for any subsequent drawing operation until a new source pattern is set. Note: The pattern's transformation matrix will be locked to the user space in effect at the time of Set_Source. This means that further modifications of the current transformation matrix will not affect the source pattern. See Cairo.Pattern.Set_Matrix. The default source pattern is a solid pattern that is opaque black, (that is, it is equivalent to Set_Source_Rgb (Cr, 0.0, 0.0, 0.0)).

Set_Source_Rgb 

procedure Set_Source_Rgb 
(Cr: Cairo_Context;
Red: Gdouble;
Green: Gdouble;
Blue: Gdouble);
Cr : a cairo context Red : Red component of color Green : Green component of color Blue : Blue component of color Sets the source pattern within Cr to an opaque color. This opaque color will then be used for any subsequent drawing operation until a new source pattern is set. The color components are floating point numbers in the range 0 to 1. If the values passed in are outside that range, they will be clamped. The default source pattern is opaque black, (that is, it is equivalent to Set_Source_Rgb (Cr, 0.0, 0.0, 0.0)).

Set_Source_Rgba 

procedure Set_Source_Rgba 
(Cr: Cairo_Context;
Red: Gdouble;
Green: Gdouble;
Blue: Gdouble;
Alpha: Gdouble);
Cr : a cairo context Red : Red component of color Green : Green component of color Blue : Blue component of color Alpha : Alpha component of color Sets the source pattern within Cr to a translucent color. This color will then be used for any subsequent drawing operation until a new source pattern is set. The color and alpha components are floating point numbers in the range 0 to 1. If the values passed in are outside that range, they will be clamped. The default source pattern is opaque black, (that is, it is equivalent to Set_Source_Rgba (Cr, 0.0, 0.0, 0.0, 1.0)).

Set_Source_Surface 

procedure Set_Source_Surface 
(Cr: Cairo_Context;
Surface: Cairo_Surface;
X: Gdouble;
Y: Gdouble);
Cr : a cairo context Surface : a Surface to be used to set the source pattern X : User-space X coordinate for surface origin Y : User-space Y coordinate for surface origin This is a convenience function for creating a pattern from surface and setting it as the source in Cr with Set_Source. The X and Y parameters give the user-space coordinate at which the surface origin should appear. (The surface origin is its upper-left corner before any transformation has been applied.) The X and Y patterns are negated and then set as translation values in the pattern matrix. Other than the initial translation pattern matrix, as described above, all other pattern attributes, (such as its extend mode), are set to the default values as in Cairo.Pattern.Create_For_Surface. The resulting pattern can be queried with Get_Source so that these attributes can be modified if desired, (eg. to create a repeating pattern with Cairo.Pattern.Set_Extend).

Set_Tolerance 

procedure Set_Tolerance 
(Cr: Cairo_Context;
Tolerance: Gdouble);
Cr: a Cairo_Context Tolerance: the Tolerance, in device units (typically pixels) Sets the tolerance used when converting paths into trapezoids. Curved segments of the path will be subdivided until the maximum deviation between the original path and the polygonal approximation is less than tolerance. The default value is 0.1. A larger value will give better performance, a smaller value, better appearance. (Reducing the value from the default value of 0.1 is unlikely to improve appearance significantly.) The accuracy of paths within Cairo is limited by the precision of its internal arithmetic, and the prescribed tolerance is restricted to the smallest representable internal value.

Set_Antialias 

procedure Set_Antialias 
(Cr: Cairo_Context;
Antialias: Cairo_Antialias);
Cr: a Cairo_Context Antialias: the new Antialiasing mode Set the antialiasing mode of the rasterizer used for drawing shapes. This value is a hint, and a particular backend may or may not support a particular value. At the current time, no backend supports Cairo_Antialias_Subpixel when drawing shapes. Note that this option does not affect text rendering, instead see Cairo.Font_Options.Set_Antialias.

Set_Fill_Rule 

procedure Set_Fill_Rule 
(Cr: Cairo_Context;
Fill_Rule: Cairo_Fill_Rule);
Cr: a Cairo_Context Fill_Rule: a fill rule Set the current fill rule within the cairo context. The fill rule is used to determine which regions are inside or outside a complex (potentially self-intersecting) path. The current fill rule affects both Fill and Clip. See Cairo_Fill_Rule for details on the semantics of each available fill rule. The default fill rule is Cairo_Fill_Rule_Winding.

Set_Line_Width 

procedure Set_Line_Width 
(Cr: Cairo_Context;
Width: Gdouble);
Cr: a Cairo_Context Width: a line Width Sets the current line width within the cairo context. The line width value specifies the diameter of a pen that is circular in user space, (though device-space pen may be an ellipse in general due to scaling/shear/rotation of the CTM). Note: When the description above refers to user space and CTM it refers to the user space and CTM in effect at the time of the stroking operation, not the user space and CTM in effect at the time of the call to Set_Line_Width. The simplest usage makes both of these spaces identical. That is, if there is no change to the CTM between a call to Set_Line_Width and the stroking operation, then one can just pass user-space values to Set_Line_Width and ignore this note. As with the other stroke parameters, the current line width is examined by Stroke, Stroke_Extents, and Stroke_To_Path, but does not have any effect during path construction. The default line width value is 2.0.

Set_Line_Cap 

procedure Set_Line_Cap 
(Cr: Cairo_Context;
Line_Cap: Cairo_Line_Cap);
Cr: a cairo context Line_Cap: a line cap style Sets the current line cap style within the cairo context. See Cairo_Line_Cap for details about how the available line cap styles are drawn. As with the other stroke parameters, the current line cap style is examined by Stroke, Stroke_Extents, and Stroke_To_Path, but does not have any effect during path construction. The default line cap style is Cairo_Line_Cap_Butt.

Set_Line_Join 

procedure Set_Line_Join 
(Cr: Cairo_Context;
Line_Join: Cairo_Line_Join);
Cr: a cairo context Line_Join: a line join style Sets the current line join style within the cairo context. See Cairo_Line_Join for details about how the available line join styles are drawn. As with the other stroke parameters, the current line join style is examined by Stroke, Stroke_Extents, and Stroke_To_Path, but does not have any effect during path construction. The default line join style is Cairo_Line_Join_Miter.

Set_Dash 

procedure Set_Dash 
(Cr: Cairo_Context;
Dashes: Dash_Array;
Offset: Gdouble);
Cr: a cairo context Dashes: an array specifying alternate lengths of on and off stroke portions Offset: an Offset into the dash pattern at which the stroke should start Sets the dash pattern to be used by Stroke. A dash pattern is specified by dashes, an array of positive values. Each value provides the length of alternate "on" and "off" portions of the stroke. The offset specifies an offset into the pattern at which the stroke begins. Each "on" segment will have caps applied as if the segment were a separate sub-path. In particular, it is valid to use an "on" length of 0.0 with Cairo_Line_Cap_Round or Cairo_Line_Cap_Square in order to distributed dots or squares along a path. Note: The length values are in user-space units as evaluated at the time of stroking. This is not necessarily the same as the user space at the time of Set_Dash. If the array is No_Dashes, dashing is disabled. If the array contains only one element symmetric pattern is assumed with alternating on and off portions of the size specified by the single value in dashes. If any value in dashes is negative, or if all values are 0, then cr will be put into an error state with a status of Cairo_Status_Invalid_Dash.

Set_Miter_Limit 

procedure Set_Miter_Limit 
(Cr: Cairo_Context;
Limit: Gdouble);
Cr: a cairo context Limit: miter Limit to set Sets the current miter limit within the cairo context. If the current line join style is set to Cairo_Line_Join_Miter (see Cairo_Set_Line_Join), the miter limit is used to determine whether the lines should be joined with a bevel instead of a miter. Cairo divides the length of the miter by the line width. If the result is greater than the miter limit, the style is converted to a bevel. As with the other stroke parameters, the current line miter limit is examined by Stroke, Stroke_Extents, and Stroke_To_Path, but does not have any effect during path construction. The default miter limit value is 10.0, which will convert joins with interior angles less than 11 degrees to bevels instead of miters. For reference, a miter limit of 2.0 makes the miter cutoff at 60 degrees, and a miter limit of 1.414 makes the cutoff at 90 degrees. A miter limit for a desired angle can be computed as: miter limit = 1/sin(angle/2)

Translate 

procedure Translate 
(Cr: Cairo_Context;
Tx: Gdouble;
Ty: Gdouble);
Cr: a cairo context Tx: amount to translate in the X direction Ty: amount to translate in the Y direction Modifies the current transformation matrix (CTM) by translating the user-space origin by (tx, ty). This offset is interpreted as a user-space coordinate according to the CTM in place before the new call to Translate. In other words, the translation of the user-space origin takes place after any existing transformation.

Scale 

procedure Scale 
(Cr: Cairo_Context;
Sx: Gdouble;
Sy: Gdouble);
Cr: a cairo context Sx: scale factor for the X dimension Sy: scale factor for the Y dimension Modifies the current transformation matrix (CTM) by scaling the X and Y user-space axes by sx and sy respectively. The scaling of the axes takes place after any existing transformation of user space.

Rotate 

procedure Rotate 
(Cr: Cairo_Context;
Angle: Gdouble);
Cr: a cairo context Angle: Angle (in radians) by which the user-space axes will be rotated Modifies the current transformation matrix (CTM) by rotating the user-space axes by angle radians. The rotation of the axes takes places after any existing transformation of user space. The rotation direction for positive angles is from the positive X axis toward the positive Y axis.

Transform 

procedure Transform 
(Cr: Cairo_Context;
Matrix: access Cairo_Matrix);
Cr: a cairo context Matrix: a transformation to be applied to the user-space axes Modifies the current transformation matrix (CTM) by applying matrix as an additional transformation. The new transformation of user space takes place after any existing transformation.

Set_Matrix 

procedure Set_Matrix 
(Cr: Cairo_Context;
Matrix: access Cairo_Matrix);
Cr: a cairo context Matrix: a transformation Matrix from user space to device space Modifies the current transformation matrix (CTM) by setting it equal to matrix.

Identity_Matrix 

procedure Identity_Matrix 
(Cr: Cairo_Context);
Cr: a cairo context Resets the current transformation matrix (CTM) by setting it equal to the identity matrix. That is, the user-space and device-space axes will be aligned and one user-space unit will transform to one device-space unit.

User_To_Device 

procedure User_To_Device 
(Cr: Cairo_Context;
X: access Gdouble;
Y: access Gdouble);
Cr: a cairo context X: X value of coordinate (in/out parameter) Y: Y value of coordinate (in/out parameter) Transform a coordinate from user space to device space by multiplying the given point by the current transformation matrix (CTM).

User_To_Device_Distance 

procedure User_To_Device_Distance 
(Cr: Cairo_Context;
Dx: access Gdouble;
Dy: access Gdouble);
Cr: a cairo context Dx: X component of a distance vector (in/out parameter) Dy: Y component of a distance vector (in/out parameter) Transform a distance vector from user space to device space. This function is similar to User_To_Device except that the translation components of the CTM will be ignored when transforming (Dx,Dy).

Device_To_User 

procedure Device_To_User 
(Cr: Cairo_Context;
X: access Gdouble;
Y: access Gdouble);
Cr: a cairo X: X value of coordinate (in/out parameter) Y: Y value of coordinate (in/out parameter) Transform a coordinate from device space to user space by multiplying the given point by the inverse of the current transformation matrix (CTM).

Device_To_User_Distance 

procedure Device_To_User_Distance 
(Cr: Cairo_Context;
Dx: access Gdouble;
Dy: access Gdouble);
Cr: a cairo context Dx: X component of a distance vector (in/out parameter) Dy: Y component of a distance vector (in/out parameter) Transform a distance vector from device space to user space. This function is similar to Device_To_User except that the translation components of the inverse CTM will be ignored when transforming (Dx,dy).

New_Path 

procedure New_Path 
(Cr: Cairo_Context);
Cr: a cairo context Clears the current path. After this call there will be no path and no current point.

Move_To 

procedure Move_To 
(Cr: Cairo_Context;
X: Gdouble;
Y: Gdouble);
Cr: a cairo context X: the X coordinate of the new position Y: the Y coordinate of the new position Begin a new sub-path. After this call the current point will be (X, Y).

New_Sub_Path 

procedure New_Sub_Path 
(Cr: Cairo_Context);
Cr: a cairo context Begin a new sub-path. Note that the existing path is not affected. After this call there will be no current point. In many cases, this call is not needed since new sub-paths are frequently started with Move_To. A call to New_Sub_Path is particularly useful when beginning a new sub-path with one of the Arc calls. This makes things easier as it is no longer necessary to manually compute the arc's initial coordinates for a call to Move_To. Since: 1.2

Line_To 

procedure Line_To 
(Cr: Cairo_Context;
X: Gdouble;
Y: Gdouble);
Cr: a cairo context X: the X coordinate of the end of the new line Y: the Y coordinate of the end of the new line Adds a line to the path from the current point to position (X, Y) in user-space coordinates. After this call the current point will be (X, Y). If there is no current point before the call to Line_To this function will behave as Move_To (Cr, X, Y).

Curve_To 

procedure Curve_To 
(Cr: Cairo_Context;
X1: Gdouble;
Y1: Gdouble;
X2: Gdouble;
Y2: Gdouble;
X3: Gdouble;
Y3: Gdouble);
Cr: a cairo context X1: the X coordinate of the first control point Y1: the Y coordinate of the first control point X2: the X coordinate of the second control point Y2: the Y coordinate of the second control point X3: the X coordinate of the end of the curve Y3: the Y coordinate of the end of the curve Adds a cubic Bézier spline to the path from the current point to position (X3, Y3) in user-space coordinates, using (X1, Y1) and (X2, Y2) as the control points. After this call the current point will be (X3, Y3). If there is no current point before the call to Curve_To this function will behave as if preceded by a call to Move_To (Cr, X1, Y1).

Arc 

procedure Arc 
(Cr: Cairo_Context;
Xc: Gdouble;
Yc: Gdouble;
Radius: Gdouble;
Angle1: Gdouble;
Angle2: Gdouble);
Cr: a cairo context Xc: X position of the center of the arc Yc: Y position of the center of the arc Radius: the Radius of the arc Angle1: the start angle, in radians Angle2: the end angle, in radians Adds a circular arc of the given radius to the current path. The arc is centered at (Xc, Yc), begins at Angle1 and proceeds in the direction of increasing angles to end at Angle2. If Angle2 is less than Angle1 it will be progressively increased by 2*M_PI until it is greater than Angle1. If there is a current point, an initial line segment will be added to the path to connect the current point to the beginning of the arc. If this initial line is undesired, it can be avoided by calling New_Sub_Path before calling Arc. Angles are measured in radians. An angle of 0.0 is in the direction of the positive X axis (in user space). An angle of M_PI/2.0 radians (90 degrees) is in the direction of the positive Y axis (in user space). Angles increase in the direction from the positive X axis toward the positive Y axis. So with the default transformation matrix, angles increase in a clockwise direction. (To convert from degrees to radians, use degrees * (Pi / 180.0)) This function gives the arc in the direction of increasing angles; see Cairo_Arc_Negative to get the arc in the direction of decreasing angles. The arc is circular in user space. To achieve an elliptical arc, you can scale the current transformation matrix by different amounts in the X and Y directions. For example, to draw an ellipse in the box given by X, Y, Width, Height: Cairo_Save (Cr); Cairo_Translate (Cr, X + Width / 2.0, Y + Height / 2.0); Cairo_Scale (Cr, Width / 2.0, Height / 2.0); Cairo_Arc (Cr, 0.0, 0.0, 1.0, 0.0, 2 * Pi); Cairo_Restore (Cr);

Arc_Negative 

procedure Arc_Negative 
(Cr: Cairo_Context;
Xc: Gdouble;
Yc: Gdouble;
Radius: Gdouble;
Angle1: Gdouble;
Angle2: Gdouble);
Cr: a cairo context Xc: X position of the center of the arc Yc: Y position of the center of the arc Radius: the Radius of the arc Angle1: the start angle, in radians Angle2: the end angle, in radians Adds a circular arc of the given radius to the current path. The arc is centered at (Xc, Yc), begins at Angle1 and proceeds in the direction of decreasing angles to end at Angle2. If Angle2 is greater than Angle1 it will be progressively decreased by 2*Pi until it is less than Angle1. See Arc for more details. This function differs only in the direction of the arc between the two angles.

Rel_Move_To 

procedure Rel_Move_To 
(Cr: Cairo_Context;
Dx: Gdouble;
Dy: Gdouble);
Cr: a cairo context Dx: the X offset Dy: the Y offset Begin a new sub-path. After this call the current point will offset by (X, Y). Given a current point of (X, Y), Rel_Move_To (Cr, Dx, Dy) is logically equivalent to Move_To (Cr, X + Dx, Y + Dy). It is an error to call this function with no current point. Doing so will cause cr to shutdown with a status of Cairo_Status_No_Current_Point.

Rel_Line_To 

procedure Rel_Line_To 
(Cr: Cairo_Context;
Dx: Gdouble;
Dy: Gdouble);
Cr: a cairo context Dx: the X offset to the end of the new line Dy: the Y offset to the end of the new line Relative-coordinate version of Line_To. Adds a line to the path from the current point to a point that is offset from the current point by (Dx, Dy) in user space. After this call the current point will be offset by (Dx, Dy). Given a current point of (X, Y), Rel_Line_To (Cr, Dx, Dy) is logically equivalent to Cairo_Line_To(Cr, X + Dx, Y + Dy). It is an error to call this function with no current point. Doing so will cause cr to shutdown with a status of Cairo_Status_No_Current_Point.

Rel_Curve_To 

procedure Rel_Curve_To 
(Cr: Cairo_Context;
Dx1: Gdouble;
Dy1: Gdouble;
Dx2: Gdouble;
Dy2: Gdouble;
Dx3: Gdouble;
Dy3: Gdouble);
Cr: a cairo context Dx1: the X offset to the first control point Dy1: the Y offset to the first control point Dx2: the X offset to the second control point Dy2: the Y offset to the second control point Dx3: the X offset to the end of the curve Dy3: the Y offset to the end of the curve Relative-coordinate version of Cairo_Curve_To. All offsets are relative to the current point. Adds a cubic Bézier spline to the path from the current point to a point offset from the current point by (Dx3, Dy3), using points offset by (Dx1, Dy1) and (Dx2, Dy2) as the control points. After this call the current point will be offset by (Dx3, Dy3). Given a current point of (X, Y), Cairo_Rel_Curve_To(Cr, Dx1, Dy1, Dx2, Dy2, Dx3, Dy3) is logically equivalent to Cairo_Curve_To(Cr, X+Dx1, Y+Dy1, X+Dx2, Y+Dy2, X+Dx3, Y+Dy3). It is an error to call this function with no current point. Doing so will cause cr to shutdown with a status of Cairo_Status_No_Current_Point.

Rectangle 

procedure Rectangle 
(Cr: Cairo_Context;
X: Gdouble;
Y: Gdouble;
Width: Gdouble;
Height: Gdouble);
Cr: a cairo context X: the X coordinate of the top left corner of the rectangle Y: the Y coordinate to the top left corner of the rectangle Width: the Width of the rectangle Height: the Height of the rectangle Adds a closed sub-path rectangle of the given size to the current path at position (X, Y) in user-space coordinates. This function is logically equivalent to: Move_To (Cr, x, Y); Rel_Line_To (Cr, Width, 0); Rel_Line_To (Cr, 0, Height); Rel_Line_To (Cr, -Width, 0); Close_Path (Cr);

Close_Path 

procedure Close_Path 
(Cr: Cairo_Context);
Cr: a cairo context Adds a line segment to the path from the current point to the beginning of the current sub-path, (the most recent point passed to Move_To), and closes this sub-path. After this call the current point will be at the joined endpoint of the sub-path. The behavior of Close_Path is distinct from simply calling Line_To with the equivalent coordinate in the case of stroking. When a closed sub-path is stroked, there are no caps on the ends of the sub-path. Instead, there is a line join connecting the final and initial segments of the sub-path. If there is no current point before the call to Close_Path, this function will have no effect. Note: As of cairo version 1.2.4 any call to Close_Path will place an explicit MOVE_TO element into the path immediately after the CLOSE_PATH element, (which can be seen in Copy_Path for example). This can simplify path processing in some cases as it may not be necessary to save the "last move_to point" during processing as the MOVE_TO immediately after the CLOSE_PATH will provide that point.

Path_Extents 

procedure Path_Extents 
(Cr: Cairo_Context;
X1: access Gdouble;
Y1: access Gdouble;
X2: access Gdouble;
Y2: access Gdouble);
Cr: a cairo context X1: left of the resulting extents Y1: top of the resulting extents X2: right of the resulting extents Y2: bottom of the resulting extents Computes a bounding box in user-space coordinates covering the points on the current path. If the current path is empty, returns an empty rectangle ((0,0), (0,0)). Stroke parameters, fill rule, surface dimensions and clipping are not taken into account. Contrast with Fill_Extents and Stroke_Extents which return the extents of only the area that would be "inked" by the corresponding drawing operations. The result of Path_Extents is defined as equivalent to the limit of Stroke_Extents with Cairo_Line_Cap_Round as the line width approaches 0.0, (but never reaching the empty-rectangle returned by Cairo_Stroke_Extents for a line width of 0.0). Specifically, this means that zero-area sub-paths such as Move_To;Line_To segments, (even degenerate cases where the coordinates to both calls are identical), will be considered as contributing to the extents. However, a lone Move_To will not contribute to the results of Path_Extents. Since: 1.6

Paint 

procedure Paint 
(Cr: Cairo_Context);
Cr: a cairo context A drawing operator that paints the current source everywhere within the current clip region.

Paint_With_Alpha 

procedure Paint_With_Alpha 
(Cr: Cairo_Context;
Alpha: Gdouble);
Cr: a cairo context Alpha: Alpha value, between 0 (transparent) and 1 (opaque) A drawing operator that paints the current source everywhere within the current clip region using a mask of constant alpha value alpha. The effect is similar to Paint, but the drawing is faded out using the alpha value.

Mask 

procedure Mask 
(Cr: Cairo_Context;
Pattern: Cairo_Pattern);
Cr: a cairo context Pattern: a Cairo_Pattern A drawing operator that paints the current source using the alpha channel of pattern as a mask. (Opaque areas of pattern are painted with the source, transparent areas are not painted.)

Mask_Surface 

procedure Mask_Surface 
(Cr: Cairo_Context;
Surface: Cairo_Surface;
Surface_X: Gdouble;
Surface_Y: Gdouble);
Cr: a cairo context Surface: a Cairo_Surface Surface_X: X coordinate at which to place the origin of surface Surface_Y: Y coordinate at which to place the origin of surface A drawing operator that paints the current source using the alpha channel of surface as a mask. (Opaque areas of surface are painted with the source, transparent areas are not painted.)

Stroke 

procedure Stroke 
(Cr: Cairo_Context);
Cr: a cairo context A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings. After Cairo_Stroke, the current path will be cleared from the cairo context. See Set_Line_Width, Set_Line_Join, Set_Line_Cap, Set_Dash, and Stroke_Preserve. Note: Degenerate segments and sub-paths are treated specially and provide a useful result. These can result in two different situations: 1. Zero-length "on" segments set in Set_Dash. If the cap style is Cairo_Line_Cap_Round or Cairo_Line_Cap_Square then these segments will be drawn as circular dots or squares respectively. In the case of Cairo_Line_Cap_Square, the orientation of the squares is determined by the direction of the underlying path. 2. A sub-path created by Cairo_Move_To followed by either a Cairo_Close_Path or one or more calls to Cairo_Line_To to the same coordinate as the Cairo_Move_To. If the cap style is Cairo_Line_Cap_Round then these sub-paths will be drawn as circular dots. Note that in the case of Cairo_Line_Cap_Square a degenerate sub-path will not be drawn at all, (since the correct orientation is indeterminate). In no case will a cap style of Cairo_Line_Cap_Butt cause anything to be drawn in the case of either degenerate segments or sub-paths.

Stroke_Preserve 

procedure Stroke_Preserve 
(Cr: Cairo_Context);
Cr: a cairo context A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings. Unlike Cairo_Stroke, Cairo_Stroke_Preserve preserves the path within the cairo context. See Set_Line_Width, Set_Line_Join, Set_Line_Cap, Set_Dash, and Stroke_Preserve.

Fill 

procedure Fill 
(Cr: Cairo_Context);
Cr: a cairo context A drawing operator that fills the current path according to the current fill rule, (each sub-path is implicitly closed before being filled). After Fill, the current path will be cleared from the cairo context. See Set_Fill_Rule and Fill_Preserve.

Fill_Preserve 

procedure Fill_Preserve 
(Cr: Cairo_Context);
Cr: a cairo context A drawing operator that fills the current path according to the current fill rule, (each sub-path is implicitly closed before being filled). Unlike Fill, Fill_Preserve preserves the path within the cairo context. See Set_Fill_Rule and Fill.

Copy_Page 

procedure Copy_Page 
(Cr: Cairo_Context);
Cr: a cairo context Emits the current page for backends that support multiple pages, but doesn't clear it, so, the contents of the current page will be retained for the next page too. Use Show_Page if you want to get an empty page after the emission. This is a convenience function that simply calls Cairo.Surface.Copy_Page on Cr's target.

Show_Page 

procedure Show_Page 
(Cr: Cairo_Context);
Cr: a cairo context Emits and clears the current page for backends that support multiple pages. Use Copy_Page if you don't want to clear the page. This is a convenience function that simply calls Cairo.Surface.Show_Page on cr's target.

In_Stroke 

function In_Stroke 
(Cr: Cairo_Context;
X: Gdouble;
Y: Gdouble) return Cairo_Bool;
Cr: a cairo context X: X coordinate of the point to test Y: Y coordinate of the point to test Tests whether the given point is inside the area that would be affected by a Stroke operation given the current path and stroking parameters. Surface dimensions and clipping are not taken into account. See Stroke, Set_Line_Width, Set_Line_Join, Set_Line_Cap, Set_Dash, and Stroke_Preserve. Return value: A non-zero value if the point is inside, or zero if outside.

In_Fill 

function In_Fill 
(Cr: Cairo_Context;
X: Gdouble;
Y: Gdouble) return Cairo_Bool;
Cr: a cairo context X: X coordinate of the point to test Y: Y coordinate of the point to test Tests whether the given point is inside the area that would be affected by a Fill operation given the current path and filling parameters. Surface dimensions and clipping are not taken into account. See Fill, Set_Fill_Rule and Fill_Preserve. Return value: A non-zero value if the point is inside, or zero if outside.

Stroke_Extents 

procedure Stroke_Extents 
(Cr: Cairo_Context;
X1: access Gdouble;
Y1: access Gdouble;
X2: access Gdouble;
Y2: access Gdouble);
Cr: a cairo context X1: left of the resulting extents Y1: top of the resulting extents X2: right of the resulting extents Y2: bottom of the resulting extents Computes a bounding box in user coordinates covering the area that would be affected, (the "inked" area), by a Stroke operation given the current path and stroke parameters. If the current path is empty, returns an empty rectangle ((0,0), (0,0)). Surface dimensions and clipping are not taken into account. Note that if the line width is set to exactly zero, then Stroke_Extents will return an empty rectangle. Contrast with Path_Extents which can be used to compute the non-empty bounds as the line width approaches zero. Note that Stroke_Extents must necessarily do more work to compute the precise inked areas in light of the stroke parameters, so Path_Extents may be more desirable for sake of performance if non-inked path extents are desired. See Stroke, Set_Line_Width, Set_Line_Join, Set_Line_Cap, Set_Dash, and Stroke_Preserve.

Fill_Extents 

procedure Fill_Extents 
(Cr: Cairo_Context;
X1: access Gdouble;
Y1: access Gdouble;
X2: access Gdouble;
Y2: access Gdouble);
Cr: a cairo context X1: left of the resulting extents Y1: top of the resulting extents X2: right of the resulting extents Y2: bottom of the resulting extents Computes a bounding box in user coordinates covering the area that would be affected, (the "inked" area), by a Fill operation given the current path and fill parameters. If the current path is empty, returns an empty rectangle ((0,0), (0,0)). Surface dimensions and clipping are not taken into account. Contrast with Path_Extents, which is similar, but returns non-zero extents for some paths with no inked area, (such as a simple line segment). Note that Fill_Extents must necessarily do more work to compute the precise inked areas in light of the fill rule, so Path_Extents may be more desirable for sake of performance if the non-inked path extents are desired. See Fill, Set_Fill_Rule and Fill_Preserve.

Reset_Clip 

procedure Reset_Clip 
(Cr: Cairo_Context);
Cr: a cairo context Reset the current clip region to its original, unrestricted state. That is, set the clip region to an infinitely large shape containing the target surface. Equivalently, if infinity is too hard to grasp, one can imagine the clip region being reset to the exact bounds of the target surface. Note that code meant to be reusable should not call Reset_Clip as it will cause results unexpected by higher-level code which calls Clip. Consider using Save and Restore around Clip as a more robust means of temporarily restricting the clip region.

Clip 

procedure Clip 
(Cr: Cairo_Context);
Cr: a cairo context Establishes a new clip region by intersecting the current clip region with the current path as it would be filled by Fill and according to the current fill rule (see Set_Fill_Rule). After Clip, the current path will be cleared from the cairo context. The current clip region affects all drawing operations by effectively masking out any changes to the surface that are outside the current clip region. Calling Clip can only make the clip region smaller, never larger. But the current clip is part of the graphics state, so a temporary restriction of the clip region can be achieved by calling Clip within a Save/Restore pair. The only other means of increasing the size of the clip region is Reset_Clip.

Clip_Preserve 

procedure Clip_Preserve 
(Cr: Cairo_Context);
Cr: a cairo context Establishes a new clip region by intersecting the current clip region with the current path as it would be filled by Fill and according to the current fill rule (see Set_Fill_Rule). Unlike Clip, Clip_Preserve preserves the path within the cairo context. The current clip region affects all drawing operations by effectively masking out any changes to the surface that are outside the current clip region. Calling Clip_Preserve can only make the clip region smaller, never larger. But the current clip is part of the graphics state, so a temporary restriction of the clip region can be achieved by calling Clip_Preserve within a Save/Restore pair. The only other means of increasing the size of the clip region is Reset_Clip.

Clip_Extents 

procedure Clip_Extents 
(Cr: Cairo_Context;
X1: access Gdouble;
Y1: access Gdouble;
X2: access Gdouble;
Y2: access Gdouble);
Cr: a cairo context X1: left of the resulting extents Y1: top of the resulting extents X2: right of the resulting extents Y2: bottom of the resulting extents Computes a bounding box in user coordinates covering the area inside the current clip. Since: 1.4

Copy_Clip_Rectangle_List 

function Copy_Clip_Rectangle_List 
(Cr: Cairo_Context) return Cairo_Rectangle_List_Access;
Cr: a cairo context Gets the current clip region as a list of rectangles in user coordinates. Never returns NULL. The status in the list may be Cairo_Status_Clip_Not_Representable to indicate that the clip region cannot be represented as a list of user-space rectangles. The status may have other values to indicate other errors. Returns: the current clip region as a list of rectangles in user coordinates, which should be destroyed using Rectangle_List_Destroy. Since: 1.4

Rectangle_List_Destroy 

procedure Rectangle_List_Destroy 
(Rectangle_List: access Cairo_Rectangle_List);
Rectangle_List: a rectangle list, as obtained from Copy_Clip_Rectangles Unconditionally frees Rectangle_List and all associated references. After this call, the Rectangle_List pointer must not be dereferenced. Since: 1.4

Select_Font_Face 

procedure Select_Font_Face 
(Cr: Cairo_Context;
Family: String;
Slant: Cairo_Font_Slant;
Weight: Cairo_Font_Weight);
Cr: a Cairo_Context Family: a font Family name, encoded in UTF-8 Slant: the Slant for the font Weight: the Weight for the font Note: The Select_Font_Face function call is part of what the cairo designers call the "toy" text API. It is convenient for short demos and simple programs, but it is not expected to be adequate for serious text-using applications. Selects a family and style of font from a simplified description as a family name, slant and weight. Cairo provides no operation to list available family names on the system (this is a "toy", remember), but the standard CSS2 generic family names, ("serif", "sans-serif", "cursive", "fantasy", "monospace"), are likely to work as expected. It is expected that most applications will need to use a more comprehensive font handling and text layout library, (for example, pango), in conjunction with cairo. If text is drawn without a call to Select_Font_Face, (nor Set_Font_Face nor Set_Scaled_Font), the default family is platform-specific, but is essentially "sans-serif". Default slant is Cairo_Font_Slant_Normal, and default weight is Cairo_Font_Weight_Normal. This function is equivalent to a call to Cairo.Font_Face.Toy_Font_Face_Create followed by Set_Font_Face.

Set_Font_Size 

procedure Set_Font_Size 
(Cr: Cairo_Context;
Size: Gdouble);
Cr: a Cairo_Context Size: the new font Size, in user space units Sets the current font matrix to a scale by a factor of size, replacing any font matrix previously set with Set_Font_Size or Set_Font_Matrix. This results in a font size of size user space units. (More precisely, this matrix will result in the font's em-square being a size by size square in user space.) If text is drawn without a call to Set_Font_Size, (nor Set_Font_Matrix nor Set_Scaled_Font), the default font size is 10.0.

Set_Font_Matrix 

procedure Set_Font_Matrix 
(Cr: Cairo_Context;
Matrix: access Cairo_Matrix);
Cr: a Cairo_Context Matrix: a Cairo_Matrix describing a transform to be applied to the current font. Sets the current font matrix to matrix. The font matrix gives a transformation from the design space of the font (in this space, the em-square is 1 unit by 1 unit) to user space. Normally, a simple scale is used (see Set_Font_Size), but a more complex font matrix can be used to shear the font or stretch it unequally along the two axes

Get_Font_Matrix 

procedure Get_Font_Matrix 
(Cr: Cairo_Context;
Matrix: access Cairo_Matrix);
Cr: a Cairo_Context Matrix: return value for the Matrix Stores the current font matrix into matrix. See Set_Font_Matrix.

Set_Font_Options 

procedure Set_Font_Options 
(Cr: Cairo_Context;
Options: Cairo_Font_Options);
Cr: a Cairo_Context Options: font Options to use Sets a set of custom font rendering options for the Cairo_Context. Rendering options are derived by merging these options with the options derived from underlying surface; if the value in options has a default value (like Cairo_Antialias_Default), then the value from the surface is used.

Get_Font_Options 

procedure Get_Font_Options 
(Cr: Cairo_Context;
Options: Cairo_Font_Options);
Cr: a Cairo_Context Options: a Cairo_Font_Options object into which to store the retrieved options. All existing values are overwritten Retrieves font rendering options set via Set_Font_Options. Note that the returned options do not include any options derived from the underlying surface; they are literally the options passed to Set_Font_Options.

Set_Font_Face 

procedure Set_Font_Face 
(Cr: Cairo_Context;
Font_Face: Cairo_Font_Face);
Cr: a Cairo_Context Font_Face: a Cairo_Font_Face, or Null_Font_Face to restore to the default font Replaces the current Cairo_Font_Face object in the Cairo_Context with font_face. The replaced font face in the Cairo_Context will be destroyed if there are no other references to it.

Get_Font_Face 

function Get_Font_Face 
(Cr: Cairo_Context) return Cairo_Font_Face;
Cr: a Cairo_Context Gets the current font face for a Cairo_Context. Return value: the current font face. This object is owned by cairo. To keep a reference to it, you must call Cairo.Font_Face.Reference. This function never returns Null_Font_Face. If memory cannot be allocated, a special "nil" Cairo_Font_Face object will be returned on which Cairo.Font_Face.Status returns Cairo_Status_No_Memory. Using this nil object will cause its error state to propagate to other objects it is passed to, (for example, calling Set_Font_Face with a nil font will trigger an error that will shutdown the Cairo_Context object).

Set_Scaled_Font 

procedure Set_Scaled_Font 
(Cr: Cairo_Context;
Scaled_Font: access Cairo_Scaled_Font);
Cr: a Cairo_Context Scaled_Font: a Cairo_Scaled_Font Replaces the current font face, font matrix, and font options in the Cairo_Context with those of the Cairo_Scaled_Font. Except for some translation, the current CTM of the Cairo_Context should be the same as that of the Cairo_Scaled_Font, which can be accessed using Cairo.Scaled_Font.Get_Ctm. Since: 1.2

Get_Scaled_Font 

function Get_Scaled_Font 
(Cr: Cairo_Context) return Cairo_Scaled_Font;
Cr: a Cairo_Context Gets the current scaled font for a Cairo_Context. Return value: the current scaled font. This object is owned by cairo. To keep a reference to it, you must call Cairo.Scaled_Font.Reference. This function never returns Null_Font_Face. If memory cannot be allocated, a special "nil" Cairo_Scaled_Font object will be returned on which Cairo.Font_Face.Status returns Cairo_Status_No_Memory. Using this nil object will cause its error state to propagate to other objects it is passed to, (for example, calling Set_Font_Face with a nil font will trigger an error that will shutdown the Cairo_Context object). Since: 1.4

Show_Text 

procedure Show_Text 
(Cr: Cairo_Context;
Utf8: String);
Cr: a cairo context Utf8: a NUL-terminated string of text encoded in UTF-8, or Null_Ptr A drawing operator that generates the shape from a string of UTF-8 characters, rendered according to the current Font_Face, Font_Size (Font_Matrix), and Font_Options. This function first computes a set of glyphs for the string of text. The first glyph is placed so that its origin is at the current point. The origin of each subsequent glyph is offset from that of the previous glyph by the advance values of the previous glyph. After this call the current point is moved to the origin of where the next glyph would be placed in this same progression. That is, the current point will be at the origin of the final glyph offset by its advance values. This allows for easy display of a single logical string with multiple calls to Show_Text. Note: The Show_Text function call is part of what the cairo designers call the "toy" text API. It is convenient for short demos and simple programs, but it is not expected to be adequate for serious text-using applications. See Show_Glyphs for the "real" text display API in cairo.

Show_Glyphs 

procedure Show_Glyphs 
(Cr: Cairo_Context;
Glyphs: access Cairo_Glyph;
Num_Glyphs: Gint);
Cr: a cairo context Glyphs: array of Glyphs to show Num_Glyphs: number of glyphs to show A drawing operator that generates the shape from an array of glyphs, rendered according to the current font face, font size (font matrix), and font options.

Text_Path 

procedure Text_Path 
(Cr: Cairo_Context;
Utf8: String);
Cr: a cairo context Utf8: a NUL-terminated string of text encoded in UTF-8, or Null_Ptr Adds closed paths for text to the current path. The generated path if filled, achieves an effect similar to that of Show_Text. Text conversion and positioning is done similar to Show_Text. Like Show_Text, After this call the current point is moved to the origin of where the next glyph would be placed in this same progression. That is, the current point will be at the origin of the final glyph offset by its advance values. This allows for chaining multiple calls to to Cairo_Text_Path without having to set current point in between. Note: The Text_Path function call is part of what the cairo designers call the "toy" text API. It is convenient for short demos and simple programs, but it is not expected to be adequate for serious text-using applications. See Glyph_Path for the "real" text path API in cairo.

Text_Extents 

procedure Text_Extents 
(Cr: Cairo_Context;
Utf8: Interfaces.C.Strings.chars_ptr;
Extents: access Cairo_Text_Extents);
Cr: a Cairo_Context Utf8: a NUL-terminated string of text encoded in UTF-8, or Null_Ptr Extents: a Cairo_Text_Extents object into which the results will be stored Gets the extents for a string of text. The extents describe a user-space rectangle that encloses the "inked" portion of the text, (as it would be drawn by Show_Text). Additionally, the x_advance and y_advance values indicate the amount by which the current point would be advanced by Cairo_Show_Text. Note that whitespace characters do not directly contribute to the size of the rectangle (extents.width and extents.height). They do contribute indirectly by changing the position of non-whitespace characters. In particular, trailing whitespace characters are likely to not affect the size of the rectangle, though they will affect the x_advance and y_advance values.

Glyph_Extents 

procedure Glyph_Extents 
(Cr: Cairo_Context;
Glyphs: access Cairo_Glyph;
Num_Glyphs: Gint;
Extents: access Cairo_Text_Extents);
Cr: a Cairo_Context Glyphs: an array of Cairo_Glyph objects Num_Glyphs: the number of elements in glyphs Extents: a Cairo_Text_Extents object into which the results will be stored Gets the extents for an array of glyphs. The extents describe a user-space rectangle that encloses the "inked" portion of the glyphs, (as they would be drawn by Show_Glyphs). Additionally, the X_Advance and Y_Advance values indicate the amount by which the current point would be advanced by Show_Glyphs. Note that whitespace glyphs do not contribute to the size of the rectangle (Extents.Width and Extents.Height).

Font_Extents 

procedure Font_Extents 
(Cr: Cairo_Context;
Extents: access Cairo_Font_Extents);
Cr: a Cairo_Context Extents: a Cairo_Font_Extents object into which the results will be stored. Gets the font extents for the currently selected font.

Get_Operator 

function Get_Operator 
(Cr: Cairo_Context) return Cairo_Operator;
Cr: a cairo context Gets the current compositing operator for a cairo context. Return value: the current compositing operator.

Get_Source 

function Get_Source 
(Cr: Cairo_Context) return Cairo_Pattern;
Cr: a cairo context Gets the current source pattern for Cr. Return value: the current source pattern. This object is owned by cairo. To keep a reference to it, you must call Cairo.Pattern.Reference.

Get_Tolerance 

function Get_Tolerance 
(Cr: Cairo_Context) return Gdouble;
Cr: a cairo context Gets the current tolerance value, as set by Set_Tolerance. Return value: the current tolerance value.

Get_Antialias 

function Get_Antialias 
(Cr: Cairo_Context) return Cairo_Antialias;
Cr: a cairo context Gets the current shape antialiasing mode, as set by Set_Antialias. Return value: the current shape antialiasing mode.

Has_Current_Point 

function Has_Current_Point 
(Cr: Cairo_Context) return Cairo_Bool;
Cr: a cairo context Returns whether a current point is defined on the current path. See Get_Current_Point for details on the current point. Return value: whether a current point is defined. Since: 1.6

Get_Current_Point 

procedure Get_Current_Point 
(Cr: Cairo_Context;
X: access Gdouble;
Y: access Gdouble);
Cr: a cairo context X: return value for X coordinate of the current point Y: return value for Y coordinate of the current point Gets the current point of the current path, which is conceptually the final point reached by the path so far. The current point is returned in the user-space coordinate system. If there is no defined current point or if cr is in an error status, X and Y will both be set to 0.0. It is possible to check this in advance with Has_Current_Point. Most path construction functions alter the current point. See the following for details on how they affect the current point: New_Path, New_Sub_Path, Append_Path, Close_Path, Move_To, Line_To, Curve_To, Rel_Move_To, Rel_Line_To, Rel_Curve_To, Arc, Arc_Negative, Rectangle, Text_Path, Glyph_Path, Stroke_To_Path. Some functions use and alter the current point but do not otherwise change current path: Show_Text. Some functions unset the current path and as a result, current point: Fill, Stroke.

Get_Fill_Rule 

function Get_Fill_Rule 
(Cr: Cairo_Context) return Cairo_Fill_Rule;
Cr: a cairo context Gets the current fill rule, as set by Set_Fill_Rule. Return value: the current fill rule.

Get_Line_Width 

function Get_Line_Width 
(Cr: Cairo_Context) return Gdouble;
Cr: a cairo context This function returns the current line width value exactly as set by Set_Line_Width. Note that the value is unchanged even if the CTM has changed between the calls to Set_Line_Width and Get_Line_Width. Return value: the current line width.

Get_Line_Cap 

function Get_Line_Cap 
(Cr: Cairo_Context) return Cairo_Line_Cap;
Cr: a cairo context Gets the current line cap style, as set by Set_Line_Cap. Return value: the current line cap style.

Get_Line_Join 

function Get_Line_Join 
(Cr: Cairo_Context) return Cairo_Line_Join;
Cr: a cairo context Gets the current line join style, as set by Set_Line_Join. Return value: the current line join style.

Get_Miter_Limit 

function Get_Miter_Limit 
(Cr: Cairo_Context) return Gdouble;
Cr: a cairo context Gets the current miter limit, as set by Set_Miter_Limit. Return value: the current miter limit.

Get_Dash_Count 

function Get_Dash_Count 
(Cr: Cairo_Context) return Gint;
Cr: a Cairo_Context This function returns the length of the dash array in cr (0 if dashing is not currently in effect). See also Set_Dash and Get_Dash. Return value: the length of the dash array, or 0 if no dash array set. Since: 1.4

Get_Dash 

procedure Get_Dash 
(Cr: Cairo_Context;
Dashes: out Dash_Array_Access;
Offset: out Gdouble);
Cr: a Cairo_Context Dashes: return value for the dash array, or null Offset: return value for the current dash Offset, or null Gets the current dash array. Since: 1.4

Get_Matrix 

procedure Get_Matrix 
(Cr: Cairo_Context;
Matrix: access Cairo_Matrix);
Cr: a cairo context Matrix: return value for the Matrix Stores the current transformation matrix (CTM) into matrix.

Get_Target 

function Get_Target 
(Cr: Cairo_Context) return Cairo_Surface;
Cr: a cairo context Gets the target surface for the cairo context as passed to Create. This function will always return a valid pointer, but the result can be a "nil" surface if cr is already in an error state, (ie. Cairo_Status /= Cairo_Status_Success). A nil surface is indicated by Cairo.Surface.Status/= Cairo_Status_Success. Return value: the target surface. This object is owned by cairo. To keep a reference to it, you must call Cairo.Surface.Reference.

Get_Group_Target 

function Get_Group_Target 
(Cr: Cairo_Context) return Cairo_Surface;
Cr: a cairo context Gets the current destination surface for the context. This is either the original target surface as passed to Create or the target surface for the current group as started by the most recent call to Push_Group or Push_Group_With_Content. This function will always return a valid pointer, but the result can be a "nil" surface if cr is already in an error state, (ie. Cairo_Status /= Cairo_Status_Success). A nil surface is indicated by Cairo_Status /= Cairo_Status_Success. Return value: the target surface. This object is owned by cairo. To keep a reference to it, you must call Cairo.Surface.Reference. Since: 1.2

Copy_Path 

function Copy_Path 
(Cr: Cairo_Context) return Cairo_Path_Access;
Cr: a cairo context Creates a copy of the current path and returns it to the user as a Cairo_Path. See Cairo_Path_Data for hints on how to iterate over the returned data structure. This function will always return a valid pointer, but the result will have no data (Data = null and Num_Data = 0), if either of the following conditions hold: -> If there is insufficient memory to copy the path. In this case Path.Status will be set to Cairo_Status_No_Memory -> If Cr is already in an error state. In this case Path.Status will contain the same status that would be returned by Status. Return value: the copy of the current path. The caller owns the returned object and should call Path_Destroy when finished with it.

Copy_Path_Flat 

function Copy_Path_Flat 
(Cr: Cairo_Context) return Cairo_Path_Access;
Cr: a cairo context Gets a flattened copy of the current path and returns it to the user as a Cairo_Path. See Cairo_Path_Data for hints on how to iterate over the returned data structure. This function is like Copy_Path except that any curves in the path will be approximated with piecewise-linear approximations, (accurate to within the current tolerance value). That is, the result is guaranteed to not have any elements of type Cairo_Path_Curve_To which will instead be replaced by a series of Cairo_Path_Line_To elements. This function will always return a valid pointer, but the result will have no data (Data = null and Num_Data = 0), if either of the following conditions hold: -> If there is insufficient memory to copy the path. In this case Path.Status will be set to Cairo_Status_No_Memory -> If Cr is already in an error state. In this case Path.Status will contain the same status that would be returned by Status. Return value: the copy of the current path. The caller owns the returned object and should call Path_Destroy when finished with it.

Append_Path 

procedure Append_Path 
(Cr: Cairo_Context;
Path: access Cairo_Path);
Cr: a cairo context Path: Path to be appended Append the path onto the current path. The path may be either the return value from one of Copy_Path or Copy_Path_Flat or it may be constructed manually. See Cairo_Path for details on how the path data structure should be initialized, and note that Path.Status must be initialized to Cairo_Status_Success.

Path_Destroy 

procedure Path_Destroy 
(Path: access Cairo_Path);
Path: a path previously returned by either Copy_Path or Copy_Path_Flat. Immediately releases all memory associated with Path. After a call to Path_Destroy the Path pointer is no longer valid and should not be used further. Note: Path_Destroy should only be called with an access to a Cairo_Path returned by a cairo function. Any path that is created manually (ie. outside of cairo) should be destroyed manually as well.

Status 

function Status 
(Cr: Cairo_Context) return Cairo_Status;
Cr: a cairo context Checks whether an error has previously occurred for this context. Returns: the current status of this context, see Cairo_Status