## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

1.     -----------------------------------------------------------------------

2.     --               GtkAda - Ada95 binding for Gtk+/Gnome               --

3.     --                                                                   --

4.     --                    Copyright (C) 2010-2013, AdaCore               --

5.     --                                                                   --

6.     -- This library is free software; you can redistribute it and/or     --

7.     -- modify it under the terms of the GNU General Public               --

8.     -- License as published by the Free Software Foundation; either      --

9.     -- version 2 of the License, or (at your option) any later version.  --

10.     --                                                                   --

11.     -- This library is distributed in the hope that it will be useful,   --

12.     -- but WITHOUT ANY WARRANTY; without even the implied warranty of    --

13.     -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU --

14.     -- General Public License for more details.                          --

15.     --                                                                   --

16.     -- You should have received a copy of the GNU General Public         --

17.     -- License along with this library; if not, write to the             --

18.     -- Free Software Foundation, Inc., 59 Temple Place - Suite 330,      --

19.     -- Boston, MA 02111-1307, USA.                                       --

20.     --                                                                   --

21.     -- As a special exception, if other files instantiate generics from  --

22.     -- this unit, or you link this unit with other files to produce an   --

23.     -- executable, this  unit  does not  by itself cause  the resulting  --

24.     -- executable to be covered by the GNU General Public License. This  --

25.     -- exception does not however invalidate any other reasons why the   --

26.     -- executable file  might be covered by the  GNU Public License.     --

27.     -----------------------------------------------------------------------

29.     --  <description>

30.     --  Bindings to the Cairo 2D graphics library.

31.     --  The Cairo_Context is the main object used when drawing with cairo. To draw

32.     --  with Cairo, you create a Context, set the target surface, and drawing

33.     --  options for the Cairo_Context, create shapes with functions like Move_To

34.     --  and Line_To, and then draw shapes with Stroke or Fill.

35.     --

36.     --  All drawing in Cairo is done on a Cairo_Context.

37.     --

38.     --  Drawing on on-screen Gtk widgets should be done in a callback to the

39.     --  "expose" event:

40.     --

41.     --  When the widget has been created, connect a drawing function:

42.     --

43.     --  <code>

44.     --     declare

45.     --        Area : Gtk_Drawing_Area;

46.     --

47.     --        package Event_Cb is new Gtk.Handlers.Return_Callback

48.     --            (Gtk_Drawing_Area_Record, Boolean);

49.     --     begin

50.     --        Gtk_New (Area);

51.     --        Event_Cb.Connect (Area, "expose_event",

52.     --                          Event_Cb.To_Marshaller (Expose_Cb'Access));

53.     --     end;

54.     --  </code>

55.     --

56.     --  In the callback, first get the context of the drawable on which you

57.     --  need to draw, using Gdk.Cairo.Create. Then do the drawing operations, and

58.     --  release the memory allocated to Cr using Cairo.Destroy.

59.     --

60.     --  In addition to drawing on on-screen widgets, drawing can also be done using

61.     --  the same Cairo calls to pixbufs (see Gdk.Cairo) to memory

62.     --  (see Cairo.Image_Surface), and to PNG files (see Cairo.Png).

63.     --

64.     --  Code samples demonstrating how to use various functionalities of Cairo

65.     --  can be found in the testcairo example, shipped with GtkAda.

66.     --  </description>

67.     --

68.     --  <c_version>1.8.8</c_version>

69.     --  <group>Cairo</group>

71.     with Ada.Unchecked_Deallocation;

73.     with System;

74.     with Interfaces.C.Strings;

76.     with GlibTo API docTo specTo body; use GlibTo API docTo specTo body;

78.     package CairoTo API docTo body is

80.        type Cairo_Context is private;

81.        --  A Cairo_Context contains the current state of the rendering device,

82.        --  including coordinates of yet to be drawn shapes.

83.        --

84.        --  Cairo contexts, as Cairo_Context objects are named, are central to

85.        --  cairo and all drawing with cairo is always done to a Cairo_Context

86.        --  object.

87.        --

88.        --  Memory management of Cairo_Context is done with subprograms

89.        --  Reference and Destroy, see below.

91.        type Cairo_Surface is private;

92.        --  A Cairo_Surface represents an image, either as the destination

93.        --  of a drawing operation or as source when drawing onto another

94.        --  surface.  To draw to a Cairo_Surface, create a cairo context

95.        --  with the surface as the target, using Create.

96.        --

97.        --  There are different subtypes of Cairo_Surface for

98.        --  different drawing backends; for example, Cairo.Image_Surface.Create

99.        --  creates a bitmap image in memory.

100.        --  The type of a surface can be queried with Cairo.Surface.Get_Type.

101.        --

102.        --  Memory management of Cairo_Surface is done with

103.        --  Cairo.Surface.Reference and Cairo.Surface.Destroy.

105.        type Cairo_Matrix is record

106.           Xx : aliased GdoubleTo API docTo spec;

107.           Yx : aliased GdoubleTo API docTo spec;

108.           Xy : aliased GdoubleTo API docTo spec;

109.           Yy : aliased GdoubleTo API docTo spec;

110.           X0 : aliased GdoubleTo API docTo spec;

111.           Y0 : aliased GdoubleTo API docTo spec;

112.        end record;

113.        --  Xx: Xx component of the affine transformation

114.        --  Yx: Yx component of the affine transformation

115.        --  Xy: Xy component of the affine transformation

116.        --  Yy: Yy component of the affine transformation

117.        --  X0: X translation component of the affine transformation

118.        --  Y0: Y translation component of the affine transformation

119.        --

120.        --  A Cairo_Matrix holds an affine transformation, such as a scale,

121.        --  rotation, shear, or a combination of those. The transformation of

122.        --  a point (X, Y) is given by:

123.        --

124.        --      X_New = Xx * X + Xy * Y + X0;

125.        --      Y_New = Yx * X + Yy * Y + Y0;

126.        pragma Convention (C_Pass_By_Copy, Cairo_MatrixTo API docTo spec);

128.        type Cairo_Matrix_Access is access Cairo_MatrixTo API docTo spec;

129.        procedure Unchecked_Free is new Ada.Unchecked_Deallocation

130.          (Cairo_MatrixTo API docTo spec, Cairo_Matrix_AccessTo API docTo spec);

132.        type Cairo_Pattern is private;

133.        --  A Cairo_Pattern represents a source when drawing onto a

134.        --  surface. There are different subtypes of Cairo_Pattern,

135.        --  for different types of sources; for example,

136.        --  Cairo.Pattern.Create_Rgb creates a pattern for a solid

137.        --  opaque color.

138.        --

139.        --  Other than various Cairo.Pattern.Create_<type>

140.        --  functions, some of the pattern types can be implicitly created

141.        --  using various Set_Source_<type> functions; for example Set_Source_Rgb.

142.        --

143.        --  The type of a pattern can be queried with Cairo.Pattern.Get_Type.

144.        --

145.        --  Memory management of Cairo_Pattern is done with

146.        --  Cairo.Pattern.Reference and Cairo.Pattern.Destroy.

148.        type Cairo_Destroy_Func is access procedure (Arg1 : System.Address);

149.        --  Data: The Data element being destroyed.

150.        --

151.        --  Cairo_destroy_func the type of function which is called when a

152.        --  data element is destroyed. It is passed the pointer to the data

153.        --  element and should free any memory and resources allocated for it.

155.        type Cairo_User_Data_Key is record

156.           Unused : aliased GintTo API docTo spec;

157.        end record;

158.        --  Unused: not used; ignore.

159.        --

160.        --  Cairo_User_Data_Key is used for attaching user data to cairo

161.        --  data structures.  The actual contents of the struct is never used,

162.        --  and there is no need to initialize the object; only the unique

163.        --  address of a Cairo_User_Data_Key object is used.  Typically, you

164.        --  would just use the address of a static Cairo_User_Data_Key object.

166.        pragma Convention (C_Pass_By_Copy, Cairo_User_Data_KeyTo API docTo spec);

168.        --  Cairo_Status is used to indicate errors that can occur when

169.        --  using Cairo. In some cases it is returned directly by functions.

170.        --  but when using Cairo_T, the last error, if any, is stored in

171.        --  the context and can be retrieved with Cairo_Status.

172.        --

173.        --  New entries may be added in future versions.  Use

174.        --  Cairo_Status_To_String

175.        --  to get a human-readable representation of an error message.

176.        type Cairo_Status is

177.          (

178.           Cairo_Status_Success,

179.           --  no error has occurred

181.           Cairo_Status_No_Memory,

182.           --  out of memory

184.           Cairo_Status_Invalid_Restore,

185.           --  Cairo_Restore called without matching Cairo_Save

187.           Cairo_Status_Invalid_Pop_Group,

188.           --  no saved group to pop

190.           Cairo_Status_No_Current_Point,

191.           --  no current point defined

193.           Cairo_Status_Invalid_Matrix,

194.           --  invalid matrix (not invertible)

196.           Cairo_Status_Invalid_Status,

197.           --  invalid value for an input Cairo_status

199.           Cairo_Status_Null_Pointer,

200.           --  NULL pointer

202.           Cairo_Status_Invalid_String,

203.           --  input string not valid UTF-8

205.           Cairo_Status_Invalid_Path_Data,

206.           --  input path data not valid

208.           Cairo_Status_Read_Error,

209.           --  error while reading from input stream

211.           Cairo_Status_Write_Error,

212.           --  error while writing to output stream

214.           Cairo_Status_Surface_Finished,

215.           --  target surface has been finished

217.           Cairo_Status_Surface_Type_Mismatch,

218.           --  the surface type is not appropriate for the operation

220.           Cairo_Status_Pattern_Type_Mismatch,

221.           --  the pattern type is not appropriate for the operation

223.           Cairo_Status_Invalid_Content,

224.           --  invalid value for an input Cairo_content

226.           Cairo_Status_Invalid_Format,

227.           --  invalid value for an input Cairo_format

229.           Cairo_Status_Invalid_Visual,

230.           --  invalid value for an input Visual*

232.           Cairo_Status_File_Not_Found,

233.           --  file not found

235.           Cairo_Status_Invalid_Dash,

236.           --  invalid value for a dash setting

238.           Cairo_Status_Invalid_Dsc_Comment,

239.           --  invalid value for a DSC comment (Since 1.2)

241.           Cairo_Status_Invalid_Index,

242.           --  invalid index passed to getter (Since 1.4)

244.           Cairo_Status_Clip_Not_Representable,

245.           --  clip region not representable in desired format (Since 1.4)

247.           Cairo_Status_Temp_File_Error,

248.           --  error creating or writing to a temporary file (Since 1.6)

250.           Cairo_Status_Invalid_Stride,

251.           --  invalid value for stride (Since 1.6)

253.           Cairo_Status_Font_Type_Mismatch,

254.           --  the font type is not appropriate for the operation (Since 1.8)

256.           Cairo_Status_User_Font_Immutable,

257.           --  the user-font is immutable (Since 1.8)

259.           Cairo_Status_User_Font_Error,

260.           --  error occurred in a user-font callback function (Since 1.8)

262.           Cairo_Status_Negative_Count,

263.           --  negative number used where it is not allowed (Since 1.8)

265.           Cairo_Status_Invalid_Clusters,

266.           --  input clusters do not represent the accompanying text and glyph

267.           --  array (Since 1.8)

269.           Cairo_Status_Invalid_Slant,

270.           --  invalid value for an input Cairo_Font_Slant (Since 1.8)

272.           Cairo_Status_Invalid_Weight

273.           --  invalid value for an input Cairo_Font_Weight (Since 1.8)

274.          );

276.        subtype Cairo_Content is GuintTo API docTo spec;

277.        --  Cairo_content is used to describe the content that a surface will

278.        --  contain, whether color information, alpha information (translucence

279.        --  vs. opacity), or both.

280.        --

281.        --  Note: The large values here are designed to keep Cairo_Content

282.        --  values distinct from Cairo_Format values so that the

283.        --  implementation can detect the error if users confuse the two types.

285.        Cairo_Content_Color       : constant Cairo_ContentTo API docTo spec := 4096;

286.        --  The surface will hold color content only.

288.        Cairo_Content_Alpha       : constant Cairo_ContentTo API docTo spec := 8192;

289.        --  CAIRO_CONTENT_ALPHA: The surface will hold alpha content only.

291.        Cairo_Content_Color_Alpha : constant Cairo_ContentTo API docTo spec := 12288;

292.        --  CAIRO_CONTENT_COLOR_ALPHA: The surface will hold color and alpha

293.        --  content.

295.        function CreateTo API docTo body (Target : Cairo_SurfaceTo API docTo spec) return Cairo_ContextTo API docTo spec;

296.        --  Target: Target surface for the context

297.        --

298.        --  Creates a new Cairo_Context with all graphics state parameters set to

299.        --  default values and with target as a target surface. The target

300.        --  surface should be constructed with a backend-specific function such

301.        --  as Cairo.Image_Surface.Create.

302.        --

303.        --  This function references target, so you can immediately

304.        --  call Cairo.Surface.Destroy on it if you don't need to

305.        --  maintain a separate reference to it.

306.        --

307.        --  Return value: a newly allocated Cairo_Context with a reference

308.        --  count of 1. The initial reference count should be released

309.        --  with Destroy when you are done using the Cairo_Context.

310.        --  This function never returns NULL. If memory cannot be

311.        --  allocated, a special Cairo_Context object will be returned on

312.        --  which Status returns Cairo_Status_No_Memory.

313.        --  You can use this object normally, but no drawing will

314.        --  be done.

316.        function ReferenceTo API docTo body (Cr : Cairo_ContextTo API docTo spec) return Cairo_ContextTo API docTo spec;

317.        --  Cr: a Cairo_Context

318.        --

319.        --  Increases the reference count on cr by one. This prevents

320.        --  cr from being destroyed until a matching call to Destroy

321.        --  is made.

322.        --

323.        --  The number of references to a Cairo_Context can be retrieved using

324.        --  Get_Reference_Count.

325.        --

326.        --  Return value: the referenced Cairo_Context.

328.        procedure DestroyTo API docTo body (Cr : Cairo_ContextTo API docTo spec);

329.        --  Cr: a Cairo_Context

330.        --

331.        --  Decreases the reference count on cr by one. If the result

332.        --  is zero, then cr and all associated resources are freed.

333.        --  See Reference.

335.        function Get_Reference_CountTo API docTo body (Cr : Cairo_ContextTo API docTo spec) return GuintTo API docTo spec;

336.        --  Cr: a Cairo_Context

337.        --

338.        --  Returns the current reference count of cr.

339.        --

340.        --  Return value: the current reference count of cr.  If the

341.        --  object is a nil object, 0 will be returned.

342.        --

343.        --  Since: 1.4

345.        function Get_User_DataTo API docTo body

346.          (Cr   : Cairo_ContextTo API docTo spec;

347.           Key  : access Cairo_User_Data_KeyTo API docTo spec)

348.           return System.Address;

349.        --  Cr: a Cairo_Context

350.        --  Key: the address of the Cairo_User_Data_Key the user data was

351.        --  attached to

352.        --

353.        --  Return user data previously attached to cr using the specified

354.        --  key.  If no user data has been attached with the given key this

355.        --  function returns NULL.

356.        --

357.        --  Return value: the user data previously attached or NULL.

358.        --

359.        --  Since: 1.4

361.        function Set_User_DataTo API docTo body

362.          (Cr        : Cairo_ContextTo API docTo spec;

363.           Key       : access Cairo_User_Data_KeyTo API docTo spec;

364.           User_Data : System.Address;

365.           Destroy   : Cairo_Destroy_FuncTo API docTo spec)

366.           return      Cairo_StatusTo API docTo spec;

367.        --  Cr: a Cairo_Context

368.        --  Key: the address of a Cairo_User_Data_Key to attach the user data to

369.        --  User_Data: the user data to attach to the Cairo_Context

370.        --  Destroy: a Cairo_Destroy_Func which will be called when the

371.        --  Cairo_Context is destroyed or when new user data is attached using the

372.        --  same key.

373.        --

374.        --  Attach user data to cr.  To remove user data from a surface,

375.        --  call this function with the key that was used to set it and NULL

376.        --  for data.

377.        --

378.        --  Return value: CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY if a

379.        --  slot could not be allocated for the user data.

380.        --

381.        --  Since: 1.4

383.        procedure SaveTo API docTo body (Cr : Cairo_ContextTo API docTo spec);

384.        --  Cr: a Cairo_Context

385.        --

386.        --  Makes a copy of the current state of cr and saves it

387.        --  on an internal stack of saved states for cr. When

388.        --  Cairo_Restore is called, cr will be restored to

389.        --  the saved state. Multiple calls to Cairo_Save and

390.        --  Cairo_Restore can be nested; each call to Cairo_Restore

391.        --  restores the state from the matching paired Cairo_Save.

392.        --

393.        --  It isn't necessary to clear all saved states before

394.        --  a Cairo_Context is freed. If the reference count of a Cairo_Context

395.        --  drops to zero in response to a call to Cairo_Destroy,

396.        --  any saved states will be freed along with the Cairo_Context.

398.        procedure RestoreTo API docTo body (Cr : Cairo_ContextTo API docTo spec);

399.        --  Cr: a Cairo_Context

400.        --

401.        --  Restores cr to the state saved by a preceding call to

402.        --  Cairo_Save and removes that state from the stack of

403.        --  saved states.

405.        procedure Push_GroupTo API docTo body (Cr : Cairo_ContextTo API docTo spec);

406.        --  Cr: a cairo context

407.        --

408.        --  Temporarily redirects drawing to an intermediate surface known as a

409.        --  group. The redirection lasts until the group is completed by a call

410.        --  to Pop_Group or Pop_Group_To_Source.

411.        --

412.        --  These calls provide the result of any drawing to the group as a pattern,

413.        --  (either as an explicit object, or set as the source pattern).

414.        --

415.        --  This group functionality can be convenient for performing

416.        --  intermediate compositing. One common use of a group is to render

417.        --  objects as opaque within the group, (so that they occlude each

418.        --  other), and then blend the result with translucence onto the

419.        --  destination.

420.        --

421.        --  Groups can be nested arbitrarily deep by making balanced calls to

422.        --  Push_Group/Pop_Group. Each call pushes/pops the new target group

423.        --  onto/from a stack.

424.        --

425.        --  The Push_Group function calls Save so that any changes to the graphics

426.        --  state will not be visible outside the group, (the pop_group functions

427.        --  call Restore).

428.        --

429.        --  By default the intermediate group will have a content type of

430.        --  Cairo_Content_Color_Alphe. Other content types can be chosen for

431.        --  the group by using Push_Group_With_Content instead.

432.        --

433.        --  As an example, here is how one might fill and stroke a path with

434.        --  translucence, but without any portion of the fill being visible

435.        --  under the stroke:

436.        --

437.        --      Push_Group (Cr);

438.        --      Set_Source (Cr, Fill_Pattern);

439.        --      Fill_Preserve (Cr);

440.        --      Set_Source (Cr, Stroke_Pattern);

441.        --      Stroke (Cr);

442.        --      Pop_Group_To_Source (Cr);

443.        --      Paint_With_Alpha (Cr, Alpha);

444.        --

445.        --  Since: 1.2

447.        procedure Push_Group_With_ContentTo API docTo body

448.          (Cr      : Cairo_ContextTo API docTo spec;

449.           Content : Cairo_ContentTo API docTo spec);

450.        --  Cr: a cairo context

451.        --  Content: a Cairo_Content indicating the type of group that

452.        --            will be created

453.        --

454.        --  Temporarily redirects drawing to an intermediate surface known as a

455.        --  group. The redirection lasts until the group is completed by a call to

456.        --  Pop_Group or Pop_Group_To_Source. These calls provide the result of any

457.        --  drawing to the group as a pattern, (either as an explicit object, or set

458.        --  as the source pattern).

459.        --

460.        --  The group will have a content type of content. The ability to control

461.        --  this content type is the only distinction between this function and

462.        --  Push_Group which you should see for a more detailed description of group

463.        --  rendering.

464.        --

465.        --  Since: 1.2

467.        function Pop_GroupTo API docTo body (Cr : Cairo_ContextTo API docTo spec) return Cairo_PatternTo API docTo spec;

468.        --  Cr: a cairo context

469.        --

470.        --  Terminates the redirection begun by a call to Push_Group or

471.        --  Push_Group_With_Content and returns a new pattern containing the results

472.        --  of all drawing operations performed to the group.

473.        --

474.        --  The Pop_Group function calls Restore, (balancing a call to Save by the

475.        --  Push_Group function), so that any changes to the graphics state will not

476.        --  be visible outside the group.

477.        --

478.        --  Return value: a newly created (surface) pattern containing the

479.        --  results of all drawing operations performed to the group. The

480.        --  caller owns the returned object and should call

481.        --  Cairo.Pattern.Destroy when finished with it.

482.        --

483.        --  Since: 1.2

485.        procedure Pop_Group_To_SourceTo API docTo body (Cr : Cairo_ContextTo API docTo spec);

486.        --  Cr: a cairo context

487.        --

488.        --  Terminates the redirection begun by a call to Push_Group or

489.        --  Push_Group_With_Content and installs the resulting pattern as the source

490.        --  pattern in the given cairo context.

491.        --

492.        --  The behavior of this function is equivalent to the sequence of

493.        --  operations:

494.        --

495.        --  declare

496.        --     Group: Cairo_Pattern := Pop_Group (Cr);

497.        --  begin

498.        --     Set_Source (Cr, Group);

499.        --     Cairo.Pattern.Destroy (Group);

500.        --  end;

501.        --

502.        --  but is more convenient as their is no need for a variable to store

503.        --  the short-lived pointer to the pattern.

504.        --

505.        --  The Pop_Group function calls Restore, (balancing a call to Save by the

506.        --  push_group function), so that any changes to the graphics state will not

507.        --  be visible outside the group.

508.        --

509.        --  Since: 1.2

511.        --  Cairo_operator is used to set the compositing operator for all cairo

512.        --  drawing operations.

513.        --

514.        --  The default operator is Cairo_Operator_Over.

515.        --

516.        --  The operators marked as "unbounded" modify their destination even

517.        --  outside of the mask layer (that is, their effect is not bound by the

518.        --  mask layer). However, their effect can still be limited by way of

519.        --  clipping.

520.        --

521.        --  To keep things simple, the operator descriptions here document the

522.        --  behavior for when both source and destination are either fully

523.        --  transparent or fully opaque. The actual implementation works for

524.        --  translucent layers too.

525.        --

526.        --  For a more detailed explanation of the effects of each operator,

527.        --  including the mathematical definitions, see

528.        --  http://cairographics.org/operators/

529.        type Cairo_Operator is

530.          (Cairo_Operator_Clear,

531.           --  clear destination layer (bounded)

533.           Cairo_Operator_Source,

534.           --  replace destination layer (bounded)

536.           Cairo_Operator_Over,

537.           --  draw source layer on top of destination layer (bounded)

539.           Cairo_Operator_In,

540.           --  draw source where there was destination content (unbounded)

542.           Cairo_Operator_Out,

543.           --  draw source where there was no destination content (unbounded)

545.           Cairo_Operator_Atop,

546.           --  draw source on top of destination content and only there

548.           Cairo_Operator_Dest,

549.           --  ignore the source

551.           Cairo_Operator_Dest_Over,

552.           --  draw destination on top of source

554.           Cairo_Operator_Dest_In,

555.           --  leave destination only where there was source content (unbounded)

557.           Cairo_Operator_Dest_Out,

558.           --  leave destination only where there was no source content

560.           Cairo_Operator_Dest_Atop,

561.           --  leave destination on top of source content and only there (unbounded)

563.           Cairo_Operator_Xor,

564.           --  source and destination are shown where there is only one of them

566.           Cairo_Operator_Add,

567.           --  source and destination layers are accumulated

569.           Cairo_Operator_Saturate

570.           --  like over, but assuming source and dest are disjoint geometries

571.          );

573.        procedure Set_OperatorTo API docTo body (Cr : Cairo_ContextTo API docTo spec; Op : Cairo_OperatorTo API docTo spec);

574.        --  Cr: a Cairo_Context

575.        --  Op: a compositing Operator, specified as a Cairo_Operator

576.        --

577.        --  Sets the compositing operator to be used for all drawing

578.        --  operations. See Cairo_Operator for details on the semantics of

579.        --  each available compositing operator.

580.        --

581.        --  The default operator is Cairo_Operator_Over.

583.        procedure Set_SourceTo API docTo body (Cr : Cairo_ContextTo API docTo spec; Source : Cairo_PatternTo API docTo spec);

584.        --  Cr: a cairo context

585.        --  Source: a Cairo_Pattern to be used as the Source for

586.        --  subsequent drawing operations.

587.        --

588.        --  Sets the source pattern within Cr to source. This pattern

589.        --  will then be used for any subsequent drawing operation until a new

590.        --  source pattern is set.

591.        --

592.        --  Note: The pattern's transformation matrix will be locked to the user

593.        --  space in effect at the time of Set_Source. This means that further

594.        --  modifications of the current transformation matrix will not affect the

595.        --  source pattern. See Cairo.Pattern.Set_Matrix.

596.        --

597.        --  The default source pattern is a solid pattern that is opaque black,

598.        --  (that is, it is equivalent to Set_Source_Rgb (Cr, 0.0, 0.0, 0.0)).

600.        procedure Set_Source_RgbTo API docTo body

601.          (Cr    : Cairo_ContextTo API docTo spec;

602.           Red   : GdoubleTo API docTo spec;

603.           Green : GdoubleTo API docTo spec;

604.           Blue  : GdoubleTo API docTo spec);

605.        --  Cr    : a cairo context

606.        --  Red   : Red component of color

607.        --  Green : Green component of color

608.        --  Blue  : Blue component of color

609.        --

610.        --  Sets the source pattern within Cr to an opaque color. This opaque

611.        --  color will then be used for any subsequent drawing operation until

612.        --  a new source pattern is set.

613.        --

614.        --  The color components are floating point numbers in the range 0 to

615.        --  1. If the values passed in are outside that range, they will be

616.        --  clamped.

617.        --

618.        --  The default source pattern is opaque black, (that is, it is

619.        --  equivalent to Set_Source_Rgb (Cr, 0.0, 0.0, 0.0)).

621.        procedure Set_Source_RgbaTo API docTo body

622.          (Cr    : Cairo_ContextTo API docTo spec;

623.           Red   : GdoubleTo API docTo spec;

624.           Green : GdoubleTo API docTo spec;

625.           Blue  : GdoubleTo API docTo spec;

626.           Alpha : GdoubleTo API docTo spec);

627.        --  Cr    : a cairo context

628.        --  Red   : Red component of color

629.        --  Green : Green component of color

630.        --  Blue  : Blue component of color

631.        --  Alpha : Alpha component of color

632.        --

633.        --  Sets the source pattern within Cr to a translucent color. This

634.        --  color will then be used for any subsequent drawing operation until

635.        --  a new source pattern is set.

636.        --

637.        --  The color and alpha components are floating point numbers in the

638.        --  range 0 to 1. If the values passed in are outside that range, they

639.        --  will be clamped.

640.        --

641.        --  The default source pattern is opaque black, (that is, it is

642.        --  equivalent to Set_Source_Rgba (Cr, 0.0, 0.0, 0.0, 1.0)).

644.        procedure Set_Source_SurfaceTo API docTo body

645.          (Cr      : Cairo_ContextTo API docTo spec;

646.           Surface : Cairo_SurfaceTo API docTo spec;

647.           X       : GdoubleTo API docTo spec;

648.           Y       : GdoubleTo API docTo spec);

649.        --  Cr      : a cairo context

650.        --  Surface : a Surface to be used to set the source pattern

651.        --  X       : User-space X coordinate for surface origin

652.        --  Y       : User-space Y coordinate for surface origin

653.        --

654.        --  This is a convenience function for creating a pattern from surface

655.        --  and setting it as the source in Cr with Set_Source.

656.        --

657.        --  The X and Y parameters give the user-space coordinate at which

658.        --  the surface origin should appear. (The surface origin is its

659.        --  upper-left corner before any transformation has been applied.) The

660.        --  X and Y patterns are negated and then set as translation values

661.        --  in the pattern matrix.

662.        --

663.        --  Other than the initial translation pattern matrix, as described

664.        --  above, all other pattern attributes, (such as its extend mode), are

665.        --  set to the default values as in Cairo.Pattern.Create_For_Surface.

666.        --  The resulting pattern can be queried with Get_Source so that these

667.        --  attributes can be modified if desired, (eg. to create a

668.        --  repeating pattern with Cairo.Pattern.Set_Extend).

670.        procedure Set_ToleranceTo API docTo body (Cr : Cairo_ContextTo API docTo spec; Tolerance : GdoubleTo API docTo spec);

671.        --  Cr: a Cairo_Context

672.        --  Tolerance: the Tolerance, in device units (typically pixels)

673.        --

674.        --  Sets the tolerance used when converting paths into trapezoids.

675.        --  Curved segments of the path will be subdivided until the maximum

676.        --  deviation between the original path and the polygonal approximation

677.        --  is less than tolerance. The default value is 0.1. A larger

678.        --  value will give better performance, a smaller value, better

679.        --  appearance. (Reducing the value from the default value of 0.1

680.        --  is unlikely to improve appearance significantly.)  The accuracy of paths

681.        --  within Cairo is limited by the precision of its internal arithmetic, and

682.        --  the prescribed tolerance is restricted to the smallest

683.        --  representable internal value.

685.        --  Specifies the type of antialiasing to do when rendering text or shapes.

686.        type Cairo_Antialias is

687.          (

688.           Cairo_Antialias_Default,

689.           --  Use the default antialiasing for the subsystem and target device

691.           Cairo_Antialias_None,

692.           --  Use a bilevel alpha mask

694.           Cairo_Antialias_Gray,

695.           --  Perform single-color antialiasing (using shades of gray for black

696.           --  text on a white background, for example).

698.           Cairo_Antialias_Subpixel

699.           --  Perform antialiasing by taking advantage of the order of subpixel

700.           --  elements on devices such as LCD panels

701.          );

703.        procedure Set_AntialiasTo API docTo body

704.          (Cr        : Cairo_ContextTo API docTo spec;

705.           Antialias : Cairo_AntialiasTo API docTo spec);

706.        --  Cr: a Cairo_Context

707.        --  Antialias: the new Antialiasing mode

708.        --

709.        --  Set the antialiasing mode of the rasterizer used for drawing shapes.

710.        --  This value is a hint, and a particular backend may or may not support

711.        --  a particular value.  At the current time, no backend supports

712.        --  Cairo_Antialias_Subpixel when drawing shapes.

713.        --

714.        --  Note that this option does not affect text rendering, instead see

715.        --  Cairo.Font_Options.Set_Antialias.

717.        --  Cairo_Fill_Rule is used to select how paths are filled. For both

718.        --  fill rules, whether or not a point is included in the fill is

719.        --  determined by taking a ray from that point to infinity and looking

720.        --  at intersections with the path. The ray can be in any direction,

721.        --  as long as it doesn't pass through the end point of a segment

722.        --  or have a tricky intersection such as intersecting tangent to the path.

723.        --  (Note that filling is not actually implemented in this way. This

724.        --  is just a description of the rule that is applied.)

725.        --

726.        --  The default fill rule is Cairo_Fill_Rule_Winding.

727.        --

728.        --  New entries may be added in future versions.

729.        type Cairo_Fill_Rule is

730.          (Cairo_Fill_Rule_Winding,

731.           --  If the path crosses the ray from left-to-right, counts +1. If the

732.           --  path crosses the ray from right to left, counts -1. (Left and right

733.           --  are determined from the perspective of looking along the ray from

734.           --  the starting point). If the total count is non-zero, the point will

735.           --  be filled.

737.           Cairo_Fill_Rule_Even_Odd

738.           --  Counts the total number of

739.           --  intersections, without regard to the orientation of the contour. If

740.           --  the total number of intersections is odd, the point will be filled.

741.          );

743.        procedure Set_Fill_RuleTo API docTo body

744.          (Cr        : Cairo_ContextTo API docTo spec;

745.           Fill_Rule : Cairo_Fill_RuleTo API docTo spec);

746.        --  Cr: a Cairo_Context

747.        --  Fill_Rule: a fill rule

748.        --

749.        --  Set the current fill rule within the cairo context. The fill rule is

750.        --  used to determine which regions are inside or outside a complex

751.        --  (potentially self-intersecting) path. The current fill rule affects both

752.        --  Fill and Clip. See Cairo_Fill_Rule for details on the semantics of each

753.        --  available fill rule.

754.        --

755.        --  The default fill rule is Cairo_Fill_Rule_Winding.

757.        procedure Set_Line_WidthTo API docTo body (Cr : Cairo_ContextTo API docTo spec; Width : GdoubleTo API docTo spec);

758.        --  Cr: a Cairo_Context

759.        --  Width: a line Width

760.        --

761.        --  Sets the current line width within the cairo context. The line

762.        --  width value specifies the diameter of a pen that is circular in

763.        --  user space, (though device-space pen may be an ellipse in general

764.        --  due to scaling/shear/rotation of the CTM).

765.        --

766.        --  Note: When the description above refers to user space and CTM it

767.        --  refers to the user space and CTM in effect at the time of the

768.        --  stroking operation, not the user space and CTM in effect at the

769.        --  time of the call to Set_Line_Width. The simplest usage

770.        --  makes both of these spaces identical. That is, if there is no

771.        --  change to the CTM between a call to Set_Line_Width and the

772.        --  stroking operation, then one can just pass user-space values to

773.        --  Set_Line_Width and ignore this note.

774.        --

775.        --  As with the other stroke parameters, the current line width is examined

776.        --  by Stroke, Stroke_Extents, and Stroke_To_Path, but does not have any

777.        --  effect during path construction.

778.        --

779.        --  The default line width value is 2.0.

781.        type Cairo_Line_Cap is

782.          (Cairo_Line_Cap_Butt,

783.           --  start(stop) the line exactly at the start(end) point

785.           Cairo_Line_Cap_Round,

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

788.           Cairo_Line_Cap_Square

789.           --  use squared ending, the center of the square is the end point

790.          );

791.        --  Specifies how to render the endpoints of the path when stroking.

792.        --

793.        --  The default line cap style is Cairo_Line_Cap_Butt.

795.        procedure Set_Line_CapTo API docTo body (Cr : Cairo_ContextTo API docTo spec; Line_Cap : Cairo_Line_CapTo API docTo spec);

796.        --  Cr: a cairo context

797.        --  Line_Cap: a line cap style

798.        --

799.        --  Sets the current line cap style within the cairo context. See

800.        --  Cairo_Line_Cap for details about how the available line cap

801.        --  styles are drawn.

802.        --

803.        --  As with the other stroke parameters, the current line cap style is

804.        --  examined by Stroke, Stroke_Extents, and Stroke_To_Path, but does not

805.        --  have any effect during path construction.

806.        --

807.        --  The default line cap style is Cairo_Line_Cap_Butt.

809.        type Cairo_Line_Join is

810.          (Cairo_Line_Join_Miter,

811.           --  use a sharp (angled) corner, see Set_Miter_Limit

813.           Cairo_Line_Join_Round,

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

816.           Cairo_Line_Join_Bevel

817.           --  use a cut-off join, the join is cut off at half the line width from

818.           --  the joint point

819.          );

820.        --  Specifies how to render the junction of two lines when stroking.

821.        --

822.        --  The default line join style is Cairo_Line_Join_Miter.

824.        procedure Set_Line_JoinTo API docTo body

825.          (Cr        : Cairo_ContextTo API docTo spec;

826.           Line_Join : Cairo_Line_JoinTo API docTo spec);

827.        --  Cr: a cairo context

828.        --  Line_Join: a line join style

829.        --

830.        --  Sets the current line join style within the cairo context. See

831.        --  Cairo_Line_Join for details about how the available line join styles are

832.        --  drawn.

833.        --

834.        --  As with the other stroke parameters, the current line join style is

835.        --  examined by Stroke, Stroke_Extents, and Stroke_To_Path, but does

836.        --  not have any effect during path construction.

837.        --

838.        --  The default line join style is Cairo_Line_Join_Miter.

840.        type Dash_Array is array (Natural range <>) of GdoubleTo API docTo spec;

842.        No_Dashes : constant Dash_ArrayTo API docTo spec (1 .. 0) := (others => 0.0);

844.        procedure Set_DashTo API docTo body

845.          (Cr         : Cairo_ContextTo API docTo spec;

846.           Dashes     : Dash_ArrayTo API docTo spec;

847.           Offset     : GdoubleTo API docTo spec);

848.        --  Cr: a cairo context

849.        --  Dashes: an array specifying alternate lengths of on and off stroke

850.        --  portions

851.        --  Offset: an Offset into the dash pattern at which the stroke should start

852.        --

853.        --  Sets the dash pattern to be used by Stroke. A dash pattern

854.        --  is specified by dashes, an array of positive values. Each value

855.        --  provides the length of alternate "on" and "off" portions of the

856.        --  stroke. The offset specifies an offset into the pattern at which

857.        --  the stroke begins.

858.        --

859.        --  Each "on" segment will have caps applied as if the segment were a

860.        --  separate sub-path. In particular, it is valid to use an "on" length

861.        --  of 0.0 with Cairo_Line_Cap_Round or Cairo_Line_Cap_Square in order

862.        --  to distributed dots or squares along a path.

863.        --

864.        --  Note: The length values are in user-space units as evaluated at the

865.        --  time of stroking. This is not necessarily the same as the user

866.        --  space at the time of Set_Dash.

867.        --

868.        --  If the array is No_Dashes, dashing is disabled.

869.        --

870.        --  If the array contains only one element symmetric pattern is assumed with

871.        --  alternating on and off portions of the size specified by the single

872.        --  value in dashes.

873.        --

874.        --  If any value in dashes is negative, or if all values are 0, then

875.        --  cr will be put into an error state with a status of

876.        --  Cairo_Status_Invalid_Dash.

878.        procedure Set_Miter_LimitTo API docTo body (Cr : Cairo_ContextTo API docTo spec; Limit : GdoubleTo API docTo spec);

879.        --  Cr: a cairo context

880.        --  Limit: miter Limit to set

881.        --

882.        --  Sets the current miter limit within the cairo context.

883.        --

884.        --  If the current line join style is set to Cairo_Line_Join_Miter

885.        --  (see Cairo_Set_Line_Join), the miter limit is used to determine

886.        --  whether the lines should be joined with a bevel instead of a miter.

887.        --  Cairo divides the length of the miter by the line width.

888.        --  If the result is greater than the miter limit, the style is

889.        --  converted to a bevel.

890.        --

891.        --  As with the other stroke parameters, the current line miter limit is

892.        --  examined by Stroke, Stroke_Extents, and Stroke_To_Path, but does not

893.        --  have any effect during path construction.

894.        --

895.        --  The default miter limit value is 10.0, which will convert joins

896.        --  with interior angles less than 11 degrees to bevels instead of

897.        --  miters. For reference, a miter limit of 2.0 makes the miter cutoff

898.        --  at 60 degrees, and a miter limit of 1.414 makes the cutoff at 90

899.        --  degrees.

900.        --

901.        --  A miter limit for a desired angle can be computed as: miter limit =

902.        --  1/sin(angle/2)

904.        procedure TranslateTo API docTo body (Cr : Cairo_ContextTo API docTo spec; Tx : GdoubleTo API docTo spec; Ty : GdoubleTo API docTo spec);

905.        --  Cr: a cairo context

906.        --  Tx: amount to translate in the X direction

907.        --  Ty: amount to translate in the Y direction

908.        --

909.        --  Modifies the current transformation matrix (CTM) by translating the

910.        --  user-space origin by (tx, ty). This offset is interpreted as a

911.        --  user-space coordinate according to the CTM in place before the new

912.        --  call to Translate. In other words, the translation of the

913.        --  user-space origin takes place after any existing transformation.

915.        procedure ScaleTo API docTo body (Cr : Cairo_ContextTo API docTo spec; Sx : GdoubleTo API docTo spec; Sy : GdoubleTo API docTo spec);

916.        --  Cr: a cairo context

917.        --  Sx: scale factor for the X dimension

918.        --  Sy: scale factor for the Y dimension

919.        --

920.        --  Modifies the current transformation matrix (CTM) by scaling the X

921.        --  and Y user-space axes by sx and sy respectively. The scaling of

922.        --  the axes takes place after any existing transformation of user

923.        --  space.

925.        procedure RotateTo API docTo body (Cr : Cairo_ContextTo API docTo spec; Angle : GdoubleTo API docTo spec);

926.        --  Cr: a cairo context

927.        --  Angle: Angle (in radians) by which the user-space axes will be

928.        --  rotated

929.        --

930.        --  Modifies the current transformation matrix (CTM) by rotating the

931.        --  user-space axes by angle radians. The rotation of the axes takes

932.        --  places after any existing transformation of user space. The

933.        --  rotation direction for positive angles is from the positive X axis

934.        --  toward the positive Y axis.

936.        procedure TransformTo API docTo body

937.          (Cr     : Cairo_ContextTo API docTo spec;

938.           Matrix : access Cairo_MatrixTo API docTo spec);

939.        --  Cr: a cairo context

940.        --  Matrix: a transformation to be applied to the user-space axes

941.        --

942.        --  Modifies the current transformation matrix (CTM) by applying

943.        --  matrix as an additional transformation. The new transformation of

944.        --  user space takes place after any existing transformation.

946.        procedure Set_MatrixTo API docTo body

947.          (Cr     : Cairo_ContextTo API docTo spec;

948.           Matrix : access Cairo_MatrixTo API docTo spec);

949.        --  Cr: a cairo context

950.        --  Matrix: a transformation Matrix from user space to device space

951.        --

952.        --  Modifies the current transformation matrix (CTM) by setting it

953.        --  equal to matrix.

955.        procedure Identity_MatrixTo API docTo body (Cr : Cairo_ContextTo API docTo spec);

956.        --  Cr: a cairo context

957.        --

958.        --  Resets the current transformation matrix (CTM) by setting it equal

959.        --  to the identity matrix. That is, the user-space and device-space

960.        --  axes will be aligned and one user-space unit will transform to one

961.        --  device-space unit.

963.        procedure User_To_DeviceTo API docTo body

964.          (Cr : Cairo_ContextTo API docTo spec;

965.           X  : access GdoubleTo API docTo spec;

966.           Y  : access GdoubleTo API docTo spec);

967.        --  Cr: a cairo context

968.        --  X: X value of coordinate (in/out parameter)

969.        --  Y: Y value of coordinate (in/out parameter)

970.        --

971.        --  Transform a coordinate from user space to device space by

972.        --  multiplying the given point by the current transformation matrix

973.        --  (CTM).

975.        procedure User_To_Device_DistanceTo API docTo body

976.          (Cr : Cairo_ContextTo API docTo spec;

977.           Dx : access GdoubleTo API docTo spec;

978.           Dy : access GdoubleTo API docTo spec);

979.        --  Cr: a cairo context

980.        --  Dx: X component of a distance vector (in/out parameter)

981.        --  Dy: Y component of a distance vector (in/out parameter)

982.        --

983.        --  Transform a distance vector from user space to device space. This

984.        --  function is similar to User_To_Device except that the translation

985.        --  components of the CTM will be ignored when transforming (Dx,Dy).

987.        procedure Device_To_UserTo API docTo body

988.          (Cr : Cairo_ContextTo API docTo spec;

989.           X  : access GdoubleTo API docTo spec;

990.           Y  : access GdoubleTo API docTo spec);

991.        --  Cr: a cairo

992.        --  X: X value of coordinate (in/out parameter)

993.        --  Y: Y value of coordinate (in/out parameter)

994.        --

995.        --  Transform a coordinate from device space to user space by

996.        --  multiplying the given point by the inverse of the current

997.        --  transformation matrix (CTM).

999.        procedure Device_To_User_DistanceTo API docTo body

1000.          (Cr : Cairo_ContextTo API docTo spec;

1001.           Dx : access GdoubleTo API docTo spec;

1002.           Dy : access GdoubleTo API docTo spec);

1003.        --  Cr: a cairo context

1004.        --  Dx: X component of a distance vector (in/out parameter)

1005.        --  Dy: Y component of a distance vector (in/out parameter)

1006.        --

1007.        --  Transform a distance vector from device space to user space. This

1008.        --  function is similar to Device_To_User except that the

1009.        --  translation components of the inverse CTM will be ignored when

1010.        --  transforming (Dx,dy).

1012.        -------------------

1013.        -- Path creation --

1014.        -------------------

1016.        procedure New_PathTo API docTo body (Cr : Cairo_ContextTo API docTo spec);

1017.        --  Cr: a cairo context

1018.        --

1019.        --  Clears the current path. After this call there will be no path and

1020.        --  no current point.

1022.        procedure Move_ToTo API docTo body (Cr : Cairo_ContextTo API docTo spec; X : GdoubleTo API docTo spec; Y : GdoubleTo API docTo spec);

1023.        --  Cr: a cairo context

1024.        --  X: the X coordinate of the new position

1025.        --  Y: the Y coordinate of the new position

1026.        --

1027.        --  Begin a new sub-path. After this call the current point will be (X, Y).

1029.        procedure New_Sub_PathTo API docTo body (Cr : Cairo_ContextTo API docTo spec);

1030.        --  Cr: a cairo context

1031.        --

1032.        --  Begin a new sub-path. Note that the existing path is not

1033.        --  affected. After this call there will be no current point.

1034.        --

1035.        --  In many cases, this call is not needed since new sub-paths are

1036.        --  frequently started with Move_To.

1037.        --

1038.        --  A call to New_Sub_Path is particularly useful when

1039.        --  beginning a new sub-path with one of the Arc calls. This

1040.        --  makes things easier as it is no longer necessary to manually

1041.        --  compute the arc's initial coordinates for a call to

1042.        --  Move_To.

1043.        --

1044.        --  Since: 1.2

1046.        procedure Line_ToTo API docTo body (Cr : Cairo_ContextTo API docTo spec; X : GdoubleTo API docTo spec; Y : GdoubleTo API docTo spec);

1047.        --  Cr: a cairo context

1048.        --  X: the X coordinate of the end of the new line

1049.        --  Y: the Y coordinate of the end of the new line

1050.        --

1051.        --  Adds a line to the path from the current point to position (X, Y)

1052.        --  in user-space coordinates. After this call the current point

1053.        --  will be (X, Y).

1054.        --

1055.        --  If there is no current point before the call to Line_To

1056.        --  this function will behave as Move_To (Cr, X, Y).

1058.        procedure Curve_ToTo API docTo body

1059.          (Cr : Cairo_ContextTo API docTo spec;

1060.           X1 : GdoubleTo API docTo spec;

1061.           Y1 : GdoubleTo API docTo spec;

1062.           X2 : GdoubleTo API docTo spec;

1063.           Y2 : GdoubleTo API docTo spec;

1064.           X3 : GdoubleTo API docTo spec;

1065.           Y3 : GdoubleTo API docTo spec);

1066.        --  Cr: a cairo context

1067.        --  X1: the X coordinate of the first control point

1068.        --  Y1: the Y coordinate of the first control point

1069.        --  X2: the X coordinate of the second control point

1070.        --  Y2: the Y coordinate of the second control point

1071.        --  X3: the X coordinate of the end of the curve

1072.        --  Y3: the Y coordinate of the end of the curve

1073.        --

1074.        --  Adds a cubic Bézier spline to the path from the current point to

1075.        --  position (X3, Y3) in user-space coordinates, using (X1, Y1) and

1076.        --  (X2, Y2) as the control points. After this call the current point

1077.        --  will be (X3, Y3).

1078.        --

1079.        --  If there is no current point before the call to Curve_To

1080.        --  this function will behave as if preceded by a call to

1081.        --  Move_To (Cr, X1, Y1).

1083.        procedure ArcTo API docTo body

1084.          (Cr     : Cairo_ContextTo API docTo spec;

1085.           Xc     : GdoubleTo API docTo spec;

1086.           Yc     : GdoubleTo API docTo spec;

1087.           Radius : GdoubleTo API docTo spec;

1088.           Angle1 : GdoubleTo API docTo spec;

1089.           Angle2 : GdoubleTo API docTo spec);

1090.        --  Cr: a cairo context

1091.        --  Xc: X position of the center of the arc

1092.        --  Yc: Y position of the center of the arc

1093.        --  Radius: the Radius of the arc

1094.        --  Angle1: the start angle, in radians

1095.        --  Angle2: the end angle, in radians

1096.        --

1097.        --  Adds a circular arc of the given radius to the current path.  The

1098.        --  arc is centered at (Xc, Yc), begins at Angle1 and proceeds in

1099.        --  the direction of increasing angles to end at Angle2. If Angle2 is

1100.        --  less than Angle1 it will be progressively increased by 2*M_PI

1101.        --  until it is greater than Angle1.

1102.        --

1103.        --  If there is a current point, an initial line segment will be added

1104.        --  to the path to connect the current point to the beginning of the

1105.        --  arc. If this initial line is undesired, it can be avoided by

1106.        --  calling New_Sub_Path before calling Arc.

1107.        --

1108.        --  Angles are measured in radians. An angle of 0.0 is in the direction

1109.        --  of the positive X axis (in user space). An angle of M_PI/2.0 radians

1110.        --  (90 degrees) is in the direction of the positive Y axis (in

1111.        --  user space). Angles increase in the direction from the positive X

1112.        --  axis toward the positive Y axis. So with the default transformation

1113.        --  matrix, angles increase in a clockwise direction.

1114.        --

1115.        --  (To convert from degrees to radians, use degrees * (Pi / 180.0))

1116.        --

1117.        --  This function gives the arc in the direction of increasing angles;

1118.        --  see Cairo_Arc_Negative to get the arc in the direction of

1119.        --  decreasing angles.

1120.        --

1121.        --  The arc is circular in user space. To achieve an elliptical arc,

1122.        --  you can scale the current transformation matrix by different

1123.        --  amounts in the X and Y directions. For example, to draw an ellipse

1124.        --  in the box given by X, Y, Width, Height:

1125.        --

1126.        --  Cairo_Save (Cr);

1127.        --  Cairo_Translate (Cr, X + Width / 2.0, Y + Height / 2.0);

1128.        --  Cairo_Scale (Cr, Width / 2.0, Height / 2.0);

1129.        --  Cairo_Arc (Cr, 0.0, 0.0, 1.0, 0.0, 2 * Pi);

1130.        --  Cairo_Restore (Cr);

1132.        procedure Arc_NegativeTo API docTo body

1133.          (Cr     : Cairo_ContextTo API docTo spec;

1134.           Xc     : GdoubleTo API docTo spec;

1135.           Yc     : GdoubleTo API docTo spec;

1136.           Radius : GdoubleTo API docTo spec;

1137.           Angle1 : GdoubleTo API docTo spec;

1138.           Angle2 : GdoubleTo API docTo spec);

1139.        --  Cr: a cairo context

1140.        --  Xc: X position of the center of the arc

1141.        --  Yc: Y position of the center of the arc

1142.        --  Radius: the Radius of the arc

1143.        --  Angle1: the start angle, in radians

1144.        --  Angle2: the end angle, in radians

1145.        --

1146.        --  Adds a circular arc of the given radius to the current path.  The

1147.        --  arc is centered at (Xc, Yc), begins at Angle1 and proceeds in

1148.        --  the direction of decreasing angles to end at Angle2. If Angle2 is

1149.        --  greater than Angle1 it will be progressively decreased by 2*Pi

1150.        --  until it is less than Angle1.

1151.        --

1152.        --  See Arc for more details. This function differs only in the

1153.        --  direction of the arc between the two angles.

1155.        procedure Rel_Move_ToTo API docTo body (Cr : Cairo_ContextTo API docTo spec; Dx : GdoubleTo API docTo spec; Dy : GdoubleTo API docTo spec);

1156.        --  Cr: a cairo context

1157.        --  Dx: the X offset

1158.        --  Dy: the Y offset

1159.        --

1160.        --  Begin a new sub-path. After this call the current point will offset

1161.        --  by (X, Y).

1162.        --

1163.        --  Given a current point of (X, Y), Rel_Move_To (Cr, Dx, Dy)

1164.        --  is logically equivalent to Move_To (Cr, X + Dx, Y + Dy).

1165.        --

1166.        --  It is an error to call this function with no current point. Doing

1167.        --  so will cause cr to shutdown with a status of

1168.        --  Cairo_Status_No_Current_Point.

1170.        procedure Rel_Line_ToTo API docTo body (Cr : Cairo_ContextTo API docTo spec; Dx : GdoubleTo API docTo spec; Dy : GdoubleTo API docTo spec);

1171.        --  Cr: a cairo context

1172.        --  Dx: the X offset to the end of the new line

1173.        --  Dy: the Y offset to the end of the new line

1174.        --

1175.        --  Relative-coordinate version of Line_To. Adds a line to the

1176.        --  path from the current point to a point that is offset from the

1177.        --  current point by (Dx, Dy) in user space. After this call the

1178.        --  current point will be offset by (Dx, Dy).

1179.        --

1180.        --  Given a current point of (X, Y), Rel_Line_To (Cr, Dx, Dy)

1181.        --  is logically equivalent to Cairo_Line_To(Cr, X + Dx, Y + Dy).

1182.        --

1183.        --  It is an error to call this function with no current point. Doing

1184.        --  so will cause cr to shutdown with a status of

1185.        --  Cairo_Status_No_Current_Point.

1187.        procedure Rel_Curve_ToTo API docTo body

1188.          (Cr  : Cairo_ContextTo API docTo spec;

1189.           Dx1 : GdoubleTo API docTo spec;

1190.           Dy1 : GdoubleTo API docTo spec;

1191.           Dx2 : GdoubleTo API docTo spec;

1192.           Dy2 : GdoubleTo API docTo spec;

1193.           Dx3 : GdoubleTo API docTo spec;

1194.           Dy3 : GdoubleTo API docTo spec);

1195.        --  Cr: a cairo context

1196.        --  Dx1: the X offset to the first control point

1197.        --  Dy1: the Y offset to the first control point

1198.        --  Dx2: the X offset to the second control point

1199.        --  Dy2: the Y offset to the second control point

1200.        --  Dx3: the X offset to the end of the curve

1201.        --  Dy3: the Y offset to the end of the curve

1202.        --

1203.        --  Relative-coordinate version of Cairo_Curve_To. All offsets are

1204.        --  relative to the current point. Adds a cubic Bézier spline to the

1205.        --  path from the current point to a point offset from the current

1206.        --  point by (Dx3, Dy3), using points offset by (Dx1, Dy1) and

1207.        --  (Dx2, Dy2) as the control points. After this call the current

1208.        --  point will be offset by (Dx3, Dy3).

1209.        --

1210.        --  Given a current point of (X, Y), Cairo_Rel_Curve_To(Cr, Dx1,

1211.        --  Dy1, Dx2, Dy2, Dx3, Dy3) is logically equivalent to

1212.        --  Cairo_Curve_To(Cr, X+Dx1, Y+Dy1, X+Dx2, Y+Dy2, X+Dx3, Y+Dy3).

1213.        --

1214.        --  It is an error to call this function with no current point. Doing

1215.        --  so will cause cr to shutdown with a status of

1216.        --  Cairo_Status_No_Current_Point.

1218.        procedure RectangleTo API docTo body

1219.          (Cr     : Cairo_ContextTo API docTo spec;

1220.           X      : GdoubleTo API docTo spec;

1221.           Y      : GdoubleTo API docTo spec;

1222.           Width  : GdoubleTo API docTo spec;

1223.           Height : GdoubleTo API docTo spec);

1224.        --  Cr: a cairo context

1225.        --  X: the X coordinate of the top left corner of the rectangle

1226.        --  Y: the Y coordinate to the top left corner of the rectangle

1227.        --  Width: the Width of the rectangle

1228.        --  Height: the Height of the rectangle

1229.        --

1230.        --  Adds a closed sub-path rectangle of the given size to the current

1231.        --  path at position (X, Y) in user-space coordinates.

1232.        --

1233.        --  This function is logically equivalent to:

1234.        --

1235.        --  Move_To (Cr, x, Y);

1236.        --  Rel_Line_To (Cr, Width, 0);

1237.        --  Rel_Line_To (Cr, 0, Height);

1238.        --  Rel_Line_To (Cr, -Width, 0);

1239.        --  Close_Path (Cr);

1241.        procedure Close_PathTo API docTo body (Cr : Cairo_ContextTo API docTo spec);

1242.        --  Cr: a cairo context

1243.        --

1244.        --  Adds a line segment to the path from the current point to the

1245.        --  beginning of the current sub-path, (the most recent point passed to

1246.        --  Move_To), and closes this sub-path. After this call the

1247.        --  current point will be at the joined endpoint of the sub-path.

1248.        --

1249.        --  The behavior of Close_Path is distinct from simply calling

1250.        --  Line_To with the equivalent coordinate in the case of

1251.        --  stroking. When a closed sub-path is stroked, there are no caps on

1252.        --  the ends of the sub-path. Instead, there is a line join connecting

1253.        --  the final and initial segments of the sub-path.

1254.        --

1255.        --  If there is no current point before the call to Close_Path,

1256.        --  this function will have no effect.

1257.        --

1258.        --  Note: As of cairo version 1.2.4 any call to Close_Path will

1259.        --  place an explicit MOVE_TO element into the path immediately after

1260.        --  the CLOSE_PATH element, (which can be seen in Copy_Path for

1261.        --  example). This can simplify path processing in some cases as it may

1262.        --  not be necessary to save the "last move_to point" during processing

1263.        --  as the MOVE_TO immediately after the CLOSE_PATH will provide that

1264.        --  point.

1266.        procedure Path_ExtentsTo API docTo body

1267.          (Cr : Cairo_ContextTo API docTo spec;

1268.           X1 : access GdoubleTo API docTo spec;

1269.           Y1 : access GdoubleTo API docTo spec;

1270.           X2 : access GdoubleTo API docTo spec;

1271.           Y2 : access GdoubleTo API docTo spec);

1272.        --  Cr: a cairo context

1273.        --  X1: left of the resulting extents

1274.        --  Y1: top of the resulting extents

1275.        --  X2: right of the resulting extents

1276.        --  Y2: bottom of the resulting extents

1277.        --

1278.        --  Computes a bounding box in user-space coordinates covering the

1279.        --  points on the current path. If the current path is empty, returns

1280.        --  an empty rectangle ((0,0), (0,0)). Stroke parameters, fill rule,

1281.        --  surface dimensions and clipping are not taken into account.

1282.        --

1283.        --  Contrast with Fill_Extents and Stroke_Extents which

1284.        --  return the extents of only the area that would be "inked" by

1285.        --  the corresponding drawing operations.

1286.        --

1287.        --  The result of Path_Extents is defined as equivalent to the

1288.        --  limit of Stroke_Extents with Cairo_Line_Cap_Round as the

1289.        --  line width approaches 0.0, (but never reaching the empty-rectangle

1290.        --  returned by Cairo_Stroke_Extents for a line width of 0.0).

1291.        --

1292.        --  Specifically, this means that zero-area sub-paths such as

1293.        --  Move_To;Line_To segments, (even degenerate cases where the coordinates

1294.        --  to both calls are identical), will be considered as contributing to the

1295.        --  extents. However, a lone Move_To will not contribute to the results of

1296.        --  Path_Extents.

1297.        --

1298.        --  Since: 1.6

1300.        --------------

1301.        -- Painting --

1302.        --------------

1304.        procedure PaintTo API docTo body (Cr : Cairo_ContextTo API docTo spec);

1305.        --  Cr: a cairo context

1306.        --

1307.        --  A drawing operator that paints the current source everywhere within

1308.        --  the current clip region.

1310.        procedure Paint_With_AlphaTo API docTo body (Cr : Cairo_ContextTo API docTo spec; Alpha : GdoubleTo API docTo spec);

1311.        --  Cr: a cairo context

1312.        --  Alpha: Alpha value, between 0 (transparent) and 1 (opaque)

1313.        --

1314.        --  A drawing operator that paints the current source everywhere within the

1315.        --  current clip region using a mask of constant alpha value alpha. The

1316.        --  effect is similar to Paint, but the drawing is faded out using the alpha

1317.        --  value.

1319.        procedure MaskTo API docTo body (Cr : Cairo_ContextTo API docTo spec; Pattern : Cairo_PatternTo API docTo spec);

1320.        --  Cr: a cairo context

1321.        --  Pattern: a Cairo_Pattern

1322.        --

1323.        --  A drawing operator that paints the current source using the alpha

1324.        --  channel of pattern as a mask. (Opaque areas of pattern are painted with

1325.        --  the source, transparent areas are not painted.)

1327.        procedure Mask_SurfaceTo API docTo body

1328.          (Cr        : Cairo_ContextTo API docTo spec;

1329.           Surface   : Cairo_SurfaceTo API docTo spec;

1330.           Surface_X : GdoubleTo API docTo spec;

1331.           Surface_Y : GdoubleTo API docTo spec);

1332.        --  Cr: a cairo context

1333.        --  Surface: a Cairo_Surface

1334.        --  Surface_X: X coordinate at which to place the origin of surface

1335.        --  Surface_Y: Y coordinate at which to place the origin of surface

1336.        --

1337.        --  A drawing operator that paints the current source

1338.        --  using the alpha channel of surface as a mask. (Opaque

1339.        --  areas of surface are painted with the source, transparent

1340.        --  areas are not painted.)

1342.        procedure StrokeTo API docTo body (Cr : Cairo_ContextTo API docTo spec);

1343.        --  Cr: a cairo context

1344.        --

1345.        --  A drawing operator that strokes the current path according to the

1346.        --  current line width, line join, line cap, and dash settings. After

1347.        --  Cairo_Stroke, the current path will be cleared from the cairo

1348.        --  context. See Set_Line_Width, Set_Line_Join, Set_Line_Cap, Set_Dash,

1349.        --  and Stroke_Preserve.

1350.        --

1351.        --  Note: Degenerate segments and sub-paths are treated specially and

1352.        --  provide a useful result. These can result in two different

1353.        --  situations:

1354.        --

1355.        --  1. Zero-length "on" segments set in Set_Dash. If the cap

1356.        --  style is Cairo_Line_Cap_Round or Cairo_Line_Cap_Square then these

1357.        --  segments will be drawn as circular dots or squares respectively. In

1358.        --  the case of Cairo_Line_Cap_Square, the orientation of the squares

1359.        --  is determined by the direction of the underlying path.

1360.        --

1361.        --  2. A sub-path created by Cairo_Move_To followed by either a

1362.        --  Cairo_Close_Path or one or more calls to Cairo_Line_To to the

1363.        --  same coordinate as the Cairo_Move_To. If the cap style is

1364.        --  Cairo_Line_Cap_Round then these sub-paths will be drawn as circular

1365.        --  dots. Note that in the case of Cairo_Line_Cap_Square a degenerate

1366.        --  sub-path will not be drawn at all, (since the correct orientation

1367.        --  is indeterminate).

1368.        --

1369.        --  In no case will a cap style of Cairo_Line_Cap_Butt cause anything

1370.        --  to be drawn in the case of either degenerate segments or sub-paths.

1372.        procedure Stroke_PreserveTo API docTo body (Cr : Cairo_ContextTo API docTo spec);

1373.        --  Cr: a cairo context

1374.        --

1375.        --  A drawing operator that strokes the current path according to the

1376.        --  current line width, line join, line cap, and dash settings. Unlike

1377.        --  Cairo_Stroke, Cairo_Stroke_Preserve preserves the path within the

1378.        --  cairo context.

1379.        --

1380.        --  See Set_Line_Width, Set_Line_Join, Set_Line_Cap, Set_Dash, and

1381.        --  Stroke_Preserve.

1383.        procedure FillTo API docTo body (Cr : Cairo_ContextTo API docTo spec);

1384.        --  Cr: a cairo context

1385.        --

1386.        --  A drawing operator that fills the current path according to the

1387.        --  current fill rule, (each sub-path is implicitly closed before being

1388.        --  filled). After Fill, the current path will be cleared from

1389.        --  the cairo context. See Set_Fill_Rule and Fill_Preserve.

1391.        procedure Fill_PreserveTo API docTo body (Cr : Cairo_ContextTo API docTo spec);

1392.        --  Cr: a cairo context

1393.        --

1394.        --  A drawing operator that fills the current path according to the

1395.        --  current fill rule, (each sub-path is implicitly closed before being

1396.        --  filled). Unlike Fill, Fill_Preserve preserves the path within the

1397.        --  cairo context.

1398.        --

1399.        --  See Set_Fill_Rule and Fill.

1401.        procedure Copy_PageTo API docTo body (Cr : Cairo_ContextTo API docTo spec);

1402.        --  Cr: a cairo context

1403.        --

1404.        --  Emits the current page for backends that support multiple pages, but

1405.        --  doesn't clear it, so, the contents of the current page will be retained

1406.        --  for the next page too.  Use Show_Page if you want to get an

1407.        --  empty page after the emission.

1408.        --

1409.        --  This is a convenience function that simply calls

1410.        --  Cairo.Surface.Copy_Page on Cr's target.

1412.        procedure Show_PageTo API docTo body (Cr : Cairo_ContextTo API docTo spec);

1413.        --  Cr: a cairo context

1414.        --

1415.        --  Emits and clears the current page for backends that support multiple

1416.        --  pages.  Use Copy_Page if you don't want to clear the page.

1417.        --

1418.        --  This is a convenience function that simply calls

1419.        --  Cairo.Surface.Show_Page on cr's target.

1421.        ------------------------

1422.        -- Insideness testing --

1423.        ------------------------

1425.        type Cairo_Bool is new Boolean;

1427.        function In_StrokeTo API docTo body

1428.          (Cr   : Cairo_ContextTo API docTo spec;

1429.           X    : GdoubleTo API docTo spec;

1430.           Y    : GdoubleTo API docTo spec)

1431.           return Cairo_BoolTo API docTo spec;

1432.        --  Cr: a cairo context

1433.        --  X: X coordinate of the point to test

1434.        --  Y: Y coordinate of the point to test

1435.        --

1436.        --  Tests whether the given point is inside the area that would be

1437.        --  affected by a Stroke operation given the current path and

1438.        --  stroking parameters. Surface dimensions and clipping are not taken

1439.        --  into account.

1440.        --

1441.        --  See Stroke, Set_Line_Width, Set_Line_Join,

1442.        --  Set_Line_Cap, Set_Dash, and Stroke_Preserve.

1443.        --

1444.        --  Return value: A non-zero value if the point is inside, or zero if

1445.        --  outside.

1447.        function In_FillTo API docTo body

1448.          (Cr   : Cairo_ContextTo API docTo spec;

1449.           X    : GdoubleTo API docTo spec;

1450.           Y    : GdoubleTo API docTo spec)

1451.           return Cairo_BoolTo API docTo spec;

1452.        --  Cr: a cairo context

1453.        --  X: X coordinate of the point to test

1454.        --  Y: Y coordinate of the point to test

1455.        --

1456.        --  Tests whether the given point is inside the area that would be

1457.        --  affected by a Fill operation given the current path and

1458.        --  filling parameters. Surface dimensions and clipping are not taken

1459.        --  into account.

1460.        --

1461.        --  See Fill, Set_Fill_Rule and Fill_Preserve.

1462.        --

1463.        --  Return value: A non-zero value if the point is inside, or zero if

1464.        --  outside.

1466.        -------------------------

1467.        -- Rectangular extents --

1468.        -------------------------

1470.        procedure Stroke_ExtentsTo API docTo body

1471.          (Cr : Cairo_ContextTo API docTo spec;

1472.           X1 : access GdoubleTo API docTo spec;

1473.           Y1 : access GdoubleTo API docTo spec;

1474.           X2 : access GdoubleTo API docTo spec;

1475.           Y2 : access GdoubleTo API docTo spec);

1476.        --  Cr: a cairo context

1477.        --  X1: left of the resulting extents

1478.        --  Y1: top of the resulting extents

1479.        --  X2: right of the resulting extents

1480.        --  Y2: bottom of the resulting extents

1481.        --

1482.        --  Computes a bounding box in user coordinates covering the area that

1483.        --  would be affected, (the "inked" area), by a Stroke

1484.        --  operation given the current path and stroke parameters.

1485.        --  If the current path is empty, returns an empty rectangle ((0,0), (0,0)).

1486.        --  Surface dimensions and clipping are not taken into account.

1487.        --

1488.        --  Note that if the line width is set to exactly zero, then

1489.        --  Stroke_Extents will return an empty rectangle. Contrast with

1490.        --  Path_Extents which can be used to compute the non-empty

1491.        --  bounds as the line width approaches zero.

1492.        --

1493.        --  Note that Stroke_Extents must necessarily do more work to

1494.        --  compute the precise inked areas in light of the stroke parameters,

1495.        --  so Path_Extents may be more desirable for sake of

1496.        --  performance if non-inked path extents are desired.

1497.        --

1498.        --  See Stroke, Set_Line_Width, Set_Line_Join, Set_Line_Cap, Set_Dash, and

1499.        --  Stroke_Preserve.

1501.        procedure Fill_ExtentsTo API docTo body

1502.          (Cr : Cairo_ContextTo API docTo spec;

1503.           X1 : access GdoubleTo API docTo spec;

1504.           Y1 : access GdoubleTo API docTo spec;

1505.           X2 : access GdoubleTo API docTo spec;

1506.           Y2 : access GdoubleTo API docTo spec);

1507.        --  Cr: a cairo context

1508.        --  X1: left of the resulting extents

1509.        --  Y1: top of the resulting extents

1510.        --  X2: right of the resulting extents

1511.        --  Y2: bottom of the resulting extents

1512.        --

1513.        --  Computes a bounding box in user coordinates covering the area that

1514.        --  would be affected, (the "inked" area), by a Fill operation

1515.        --  given the current path and fill parameters. If the current path is

1516.        --  empty, returns an empty rectangle ((0,0), (0,0)). Surface

1517.        --  dimensions and clipping are not taken into account.

1518.        --

1519.        --  Contrast with Path_Extents, which is similar, but returns

1520.        --  non-zero extents for some paths with no inked area, (such as a

1521.        --  simple line segment).

1522.        --

1523.        --  Note that Fill_Extents must necessarily do more work to

1524.        --  compute the precise inked areas in light of the fill rule, so

1525.        --  Path_Extents may be more desirable for sake of performance

1526.        --  if the non-inked path extents are desired.

1527.        --

1528.        --  See Fill, Set_Fill_Rule and Fill_Preserve.

1530.        --------------

1531.        -- Clipping --

1532.        --------------

1534.        procedure Reset_ClipTo API docTo body (Cr : Cairo_ContextTo API docTo spec);

1535.        --  Cr: a cairo context

1536.        --

1537.        --  Reset the current clip region to its original, unrestricted

1538.        --  state. That is, set the clip region to an infinitely large shape

1539.        --  containing the target surface. Equivalently, if infinity is too

1540.        --  hard to grasp, one can imagine the clip region being reset to the

1541.        --  exact bounds of the target surface.

1542.        --

1543.        --  Note that code meant to be reusable should not call

1544.        --  Reset_Clip as it will cause results unexpected by higher-level code

1545.        --  which calls Clip. Consider using Save and Restore around Clip as a more

1546.        --  robust means of temporarily restricting the clip region.

1548.        procedure ClipTo API docTo body (Cr : Cairo_ContextTo API docTo spec);

1549.        --  Cr: a cairo context

1550.        --

1551.        --  Establishes a new clip region by intersecting the current clip

1552.        --  region with the current path as it would be filled by Fill

1553.        --  and according to the current fill rule (see Set_Fill_Rule).

1554.        --

1555.        --  After Clip, the current path will be cleared from the cairo

1556.        --  context.

1557.        --

1558.        --  The current clip region affects all drawing operations by

1559.        --  effectively masking out any changes to the surface that are outside

1560.        --  the current clip region.

1561.        --

1562.        --  Calling Clip can only make the clip region smaller, never

1563.        --  larger. But the current clip is part of the graphics state, so a

1564.        --  temporary restriction of the clip region can be achieved by

1565.        --  calling Clip within a Save/Restore

1566.        --  pair. The only other means of increasing the size of the clip

1567.        --  region is Reset_Clip.

1569.        procedure Clip_PreserveTo API docTo body (Cr : Cairo_ContextTo API docTo spec);

1570.        --  Cr: a cairo context

1571.        --

1572.        --  Establishes a new clip region by intersecting the current clip

1573.        --  region with the current path as it would be filled by Fill

1574.        --  and according to the current fill rule (see Set_Fill_Rule).

1575.        --

1576.        --  Unlike Clip, Clip_Preserve preserves the path within

1577.        --  the cairo context.

1578.        --

1579.        --  The current clip region affects all drawing operations by

1580.        --  effectively masking out any changes to the surface that are outside

1581.        --  the current clip region.

1582.        --

1583.        --  Calling Clip_Preserve can only make the clip region smaller, never

1584.        --  larger. But the current clip is part of the graphics state, so a

1585.        --  temporary restriction of the clip region can be achieved by

1586.        --  calling Clip_Preserve within a Save/Restore

1587.        --  pair. The only other means of increasing the size of the clip

1588.        --  region is Reset_Clip.

1590.        procedure Clip_ExtentsTo API docTo body

1591.          (Cr : Cairo_ContextTo API docTo spec;

1592.           X1 : access GdoubleTo API docTo spec;

1593.           Y1 : access GdoubleTo API docTo spec;

1594.           X2 : access GdoubleTo API docTo spec;

1595.           Y2 : access GdoubleTo API docTo spec);

1596.        --  Cr: a cairo context

1597.        --  X1: left of the resulting extents

1598.        --  Y1: top of the resulting extents

1599.        --  X2: right of the resulting extents

1600.        --  Y2: bottom of the resulting extents

1601.        --

1602.        --  Computes a bounding box in user coordinates covering the area inside the

1603.        --  current clip.

1604.        --

1605.        --  Since: 1.4

1607.        type Cairo_Rectangle is record

1608.           X      : aliased GdoubleTo API docTo spec;

1609.           Y      : aliased GdoubleTo API docTo spec;

1610.           Width  : aliased GdoubleTo API docTo spec;

1611.           Height : aliased GdoubleTo API docTo spec;

1612.        end record;

1613.        --  X: X coordinate of the left side of the rectangle

1614.        --  Y: Y coordinate of the the top side of the rectangle

1615.        --  Width: Width of the rectangle

1616.        --  Height: Height of the rectangle

1617.        --

1618.        --  A data structure for holding a rectangle.

1619.        --

1620.        --  Since: 1.4

1622.        type Cairo_Rectangle_Array is array (Natural) of Cairo_RectangleTo API docTo spec;

1623.        type Cairo_Rectangle_Array_Access is access all Cairo_Rectangle_ArrayTo API docTo spec;

1625.        type Cairo_Rectangle_List is record

1626.           Status         : aliased Cairo_StatusTo API docTo spec;

1627.           Rectangles     : Cairo_Rectangle_Array_AccessTo API docTo spec;

1628.           --  Warning: for efficiency reasons, Rectangles is a direct mapping to

1629.           --  the C structure. Therefore, there is no bounds checking on this

1630.           --  array, user needs to make sure only to access data between indexes 0

1631.           --  and Num_Rectanges-1.

1632.           Num_Rectangles : aliased GintTo API docTo spec;

1633.        end record;

1634.        --  Status: Error Status of the rectangle list

1635.        --  Rectangles: Array containing the Rectangles

1636.        --  Num_Rectangles: Number of rectangles in this list

1637.        --

1638.        --  A data structure for holding a Dynamically allocated

1639.        --  array of rectangles.

1640.        --

1641.        --  Since: 1.4

1642.        pragma Convention (C_Pass_By_Copy, Cairo_Rectangle_ListTo API docTo spec);

1644.        type Cairo_Rectangle_List_Access is access all Cairo_Rectangle_ListTo API docTo spec;

1646.        function Copy_Clip_Rectangle_ListTo API docTo body

1647.          (Cr   : Cairo_ContextTo API docTo spec)

1648.           return Cairo_Rectangle_List_AccessTo API docTo spec;

1649.        --  Cr: a cairo context

1650.        --

1651.        --  Gets the current clip region as a list of rectangles in user

1652.        --  coordinates.

1653.        --  Never returns NULL.

1654.        --

1655.        --  The status in the list may be Cairo_Status_Clip_Not_Representable to

1656.        --  indicate that the clip region cannot be represented as a list of

1657.        --  user-space rectangles. The status may have other values to indicate

1658.        --  other errors.

1659.        --

1660.        --  Returns: the current clip region as a list of rectangles in user

1661.        --  coordinates,

1662.        --  which should be destroyed using Rectangle_List_Destroy.

1663.        --

1664.        --  Since: 1.4

1666.        procedure Rectangle_List_DestroyTo API docTo body

1667.          (Rectangle_List : access Cairo_Rectangle_ListTo API docTo spec);

1668.        --  Rectangle_List: a rectangle list, as obtained from Copy_Clip_Rectangles

1669.        --

1670.        --  Unconditionally frees Rectangle_List and all associated

1671.        --  references. After this call, the Rectangle_List pointer must not

1672.        --  be dereferenced.

1673.        --

1674.        --  Since: 1.4

1676.        -------------------------

1677.        -- Font/Text functions --

1678.        -------------------------

1680.        type Cairo_Scaled_Font is private;

1681.        --  A Cairo_Scaled_Font is a font scaled to a particular size and device

1682.        --  resolution. A Cairo_Scaled_Font is most useful for low-level font

1683.        --  usage where a library or application wants to cache a reference

1684.        --  to a scaled font to speed up the computation of metrics.

1685.        --

1686.        --  There are various types of scaled fonts, depending on the font backend

1687.        --  they use. The type of a scaled font can be queried using

1688.        --  Cairo.Scaled_Font.Get_Type.

1689.        --

1690.        --  Memory management of Cairo_Scaled_Font is done with

1691.        --  Cairo.Scaled_Font.Reference and Cairo.Scaled_Font.Destroy.

1693.        type Cairo_Font_Face is private;

1694.        --  A Cairo_Font_Face specifies all aspects of a font other

1695.        --  than the size or font matrix (a font matrix is used to distort

1696.        --  a font by sheering it or scaling it unequally in the two

1697.        --  directions) . A font face can be set on a Cairo_Context by using

1698.        --  Set_Font_Face; the size and font matrix are set with

1699.        --  Set_Font_Size and Set_Font_Matrix.

1700.        --

1701.        --  There are various types of font faces, depending on the font backend

1702.        --  they use. The type of a font face can be queried using

1703.        --  Cairo.Font_Face.Get_Type.

1704.        --

1705.        --  Memory management of Cairo_Font_Face is done with

1706.        --  Cairo.Font_Face.Reference and Cairo.Font_Face.Destroy.

1707.        --

1708.        --  The Cairo_glyph structure holds information about a single glyph when

1709.        --  drawing or measuring text. A font is (in simple terms) a collection of

1710.        --  shapes used to draw text. A glyph is one of these shapes. There can be

1711.        --  multiple glyphs for a single character (alternates to be used in

1712.        --  different contexts, for example), or a glyph can be a ligature of

1713.        --  multiple characters. Cairo doesn't expose any way of converting input

1714.        --  text into glyphs, so in order to use the Cairo interfaces that take

1715.        --  arrays of glyphs, you must directly access the appropriate underlying

1716.        --  font system.

1717.        --

1718.        --  Note that the offsets given by X and Y are not cumulative. When

1719.        --  drawing or measuring text, each glyph is individually positioned

1720.        --  with respect to the overall origin

1721.        type Cairo_Glyph is record

1722.           Index : aliased GulongTo API docTo spec;

1723.           --  Glyph Index in the font. The exact interpretation of the

1724.           --  glyph index depends on the font technology being used.

1726.           X     : aliased GdoubleTo API docTo spec;

1727.           --  The offset in the X direction between the origin used for

1728.           --  drawing or measuring the string and the origin of this glyph.

1730.           Y     : aliased GdoubleTo API docTo spec;

1731.           --  The offset in the Y direction between the origin used for drawing or

1732.           --  measuring the string and the origin of this glyph.

1733.        end record;

1734.        pragma Convention (C_Pass_By_Copy, Cairo_GlyphTo API docTo spec);

1736.        type Cairo_Text_Cluster is record

1737.           Num_Bytes  : aliased GintTo API docTo spec;

1738.           --  The number of bytes of UTF-8 text covered by cluster

1740.           Num_Glyphs : aliased GintTo API docTo spec;

1741.           --  The number of glyphs covered by cluster

1742.        end record;

1743.        --  The Cairo_text_cluster structure holds information about a single text

1744.        --  cluster. A text cluster is a minimal mapping of some glyphs

1745.        --  corresponding to some UTF-8 text.

1746.        --

1747.        --  For a cluster to be valid, both num_bytes and num_glyphs should

1748.        --  be non-negative, and at least one should be non-zero.

1749.        --  Note that clusters with zero glyphs are not as well supported as

1750.        --  normal clusters.  For example, PDF rendering applications typically

1751.        --  ignore those clusters when PDF text is being selected.

1752.        --

1753.        --  See Show_Text_Glyphs for how clusters are used in advanced

1754.        --  text operations.

1755.        --

1756.        --  Since: 1.8

1757.        pragma Convention (C_Pass_By_Copy, Cairo_Text_ClusterTo API docTo spec);

1759.        subtype Cairo_Text_Cluster_Flags is GuintTo API docTo spec;

1760.        --  Specifies properties of a text cluster mapping.

1761.        --

1762.        --  Since: 1.8

1764.        Cairo_Text_Cluster_Flag_Backward : constant Cairo_Text_Cluster_FlagsTo API docTo spec := 1;

1765.        --  The clusters in the cluster array map to glyphs in the glyph array from

1766.        --  end to start.

1768.        type Cairo_Text_Extents is record

1769.           X_Bearing : aliased GdoubleTo API docTo spec;

1770.           --  The horizontal distance from the origin to the

1771.           --  leftmost part of the glyphs as drawn. Positive if the

1772.           --  glyphs lie entirely to the right of the origin.

1774.           Y_Bearing : aliased GdoubleTo API docTo spec;

1775.           --  The vertical distance from the origin to the

1776.           --  topmost part of the glyphs as drawn. Positive only if the

1777.           --  glyphs lie completely below the origin; will usually be

1778.           --  negative.

1780.           Width     : aliased GdoubleTo API docTo spec;

1781.           --  Width of the glyphs as drawn

1783.           Height    : aliased GdoubleTo API docTo spec;

1784.           --  Height of the glyphs as drawn

1786.           X_Advance : aliased GdoubleTo API docTo spec;

1787.           --  Distance to advance in the X direction after drawing these glyphs

1789.           Y_Advance : aliased GdoubleTo API docTo spec;

1790.           --  Distance to advance in the Y direction

1791.           --  after drawing these glyphs. Will typically be zero except

1792.           --  for vertical text layout as found in East-Asian languages.

1793.        end record;

1794.        --  The Cairo_text_extents structure stores the extents of a single glyph

1795.        --  or a string of glyphs in user-space coordinates. Because text extents

1796.        --  are in user-space coordinates, they are mostly, but not entirely,

1797.        --  independent of the current transformation matrix. If you call

1798.        --  Scale (Cr, 2.0, 2.0), text will be drawn twice as big, but the reported

1799.        --  text extents will not be doubled. They will change slightly due to

1800.        --  hinting (so you can't assume that metrics are independent of the

1801.        --  transformation matrix), but otherwise will remain unchanged.

1802.        pragma Convention (C_Pass_By_Copy, Cairo_Text_ExtentsTo API docTo spec);

1804.        type Cairo_Font_Extents is record

1805.           Ascent        : aliased GdoubleTo API docTo spec;

1806.           --  The distance that the font extends above the baseline.

1807.           --  Note that this is not always exactly equal to the maximum

1808.           --  of the extents of all the glyphs in the font, but rather

1809.           --  is picked to express the font designer's intent as to

1810.           --  how the font should align with elements above it.

1812.           Descent       : aliased GdoubleTo API docTo spec;

1813.           --  The distance that the font extends below the baseline.

1814.           --  This value is positive for typical fonts that include

1815.           --  portions below the baseline. Note that this is not always

1816.           --  exactly equal to the maximum of the extents of all the

1817.           --  glyphs in the font, but rather is picked to express the

1818.           --  font designer's intent as to how the the font should

1819.           --  align with elements below it.

1821.           Height        : aliased GdoubleTo API docTo spec;

1822.           --  The recommended vertical distance between baselines when

1823.           --  setting consecutive lines of text with the font. This

1824.           --  is greater than ascent+descent by a

1825.           --  quantity known as the line spacing or external leading. When space is

1826.           --  at a premium, most fonts can be set with only a distance of

1827.           --  ascent+descent between lines.

1829.           Max_X_Advance : aliased GdoubleTo API docTo spec;

1830.           --  The maximum distance in the X direction that

1831.           --  the the origin is advanced for any glyph in the font.

1833.           Max_Y_Advance : aliased GdoubleTo API docTo spec;

1834.           --  The maximum distance in the Y direction that

1835.           --  the the origin is advanced for any glyph in the font.

1836.           --  this will be zero for normal fonts used for horizontal

1837.           --  writing. (The scripts of East Asia are sometimes written

1838.           --  vertically.)

1839.        end record;

1840.        --  The Cairo_font_extents structure stores metric information for

1841.        --  a font. Values are given in the current user-space coordinate

1842.        --  system.

1843.        --

1844.        --  Because font metrics are in user-space coordinates, they are

1845.        --  mostly, but not entirely, independent of the current transformation

1846.        --  matrix. If you call Scale (Cr, 2.0, 2.0), text will be drawn twice as

1847.        --  big, but the reported text extents will not be doubled. They will

1848.        --  change slightly due to hinting (so you can't assume that metrics are

1849.        --  independent of the transformation matrix), but otherwise will remain

1850.        --  unchanged.

1851.        pragma Convention (C_Pass_By_Copy, Cairo_Font_ExtentsTo API docTo spec);

1853.        type Cairo_Font_Slant is (

1854.                                  Cairo_Font_Slant_Normal,

1855.                                  Cairo_Font_Slant_Italic,

1856.                                  Cairo_Font_Slant_Oblique);

1857.        --  Specifies variants of a font face based on their slant.

1858.        pragma Convention (C, Cairo_Font_SlantTo API docTo spec);

1860.        type Cairo_Font_Weight is (

1861.                                   Cairo_Font_Weight_Normal,

1862.                                   Cairo_Font_Weight_Bold);

1863.        --  Specifies variants of a font face based on their weight.

1864.        pragma Convention (C, Cairo_Font_WeightTo API docTo spec);

1866.        type Cairo_Subpixel_Order is

1867.          (Cairo_Subpixel_Order_Default,

1868.           --  Use the default subpixel order for the target device

1870.           Cairo_Subpixel_Order_Rgb,

1871.           --  Subpixel elements are arranged horizontally with red at the left

1873.           Cairo_Subpixel_Order_Bgr,

1874.           --  Subpixel elements are arranged horizontally with blue at the left

1876.           Cairo_Subpixel_Order_Vrgb,

1877.           --  Subpixel elements are arranged vertically with red at the top

1879.           Cairo_Subpixel_Order_Vbgr

1880.           --  Subpixel elements are arranged vertically with blue at the top

1881.          );

1882.        --  The subpixel order specifies the order of color elements within

1883.        --  each pixel on the display device when rendering with an

1884.        --  antialiasing mode of CAIRO_ANTIALIAS_SUBPIXEL.

1885.        pragma Convention (C, Cairo_Subpixel_OrderTo API docTo spec);

1887.        type Cairo_Hint_Style is

1888.          (Cairo_Hint_Style_Default,

1889.           --  Use the default hint style for font backend and target device

1891.           Cairo_Hint_Style_None,

1892.           --  Do not hint outlines

1894.           Cairo_Hint_Style_Slight,

1895.           --  Hint outlines slightly to improve contrast while retaining good

1896.           --  fidelity to the original shapes.

1898.           Cairo_Hint_Style_Medium,

1899.           --  Hint outlines with medium strength giving a compromise between

1900.           --  fidelity to the original shapes and contrast

1902.           Cairo_Hint_Style_Full

1903.           --  Hint outlines to maximize contrast

1904.          );

1905.        --  Specifies the type of hinting to do on font outlines. Hinting

1906.        --  is the process of fitting outlines to the pixel grid in order

1907.        --  to improve the appearance of the result. Since hinting outlines

1908.        --  involves distorting them, it also reduces the faithfulness

1909.        --  to the original outline shapes. Not all of the outline hinting

1910.        --  styles are supported by all font backends.

1911.        --

1912.        --  New entries may be added in future versions.

1913.        pragma Convention (C, Cairo_Hint_StyleTo API docTo spec);

1915.        type Cairo_Hint_Metrics is

1916.          (Cairo_Hint_Metrics_Default,

1917.           --  Hint metrics in the default manner for the font backend and target

1918.           --  device

1920.           Cairo_Hint_Metrics_Off,

1921.           --  Do not hint font metrics

1923.           Cairo_Hint_Metrics_On

1924.           --  Hint font metrics

1925.          );

1926.        --  Specifies whether to hint font metrics; hinting font metrics

1927.        --  means quantizing them so that they are integer values in

1928.        --  device space. Doing this improves the consistency of

1929.        --  letter and line spacing, however it also means that text

1930.        --  will be laid out differently at different zoom factors.

1931.        pragma Convention (C, Cairo_Hint_MetricsTo API docTo spec);

1933.        type Cairo_Font_Options is private;

1934.        --  An opaque structure holding all options that are used when

1935.        --  rendering fonts.

1936.        --

1937.        --  Individual features of a Cairo_Font_Options can be set or

1938.        --  accessed using functions named

1939.        --  Cairo.Font_Options.Set_<feature_Name> and

1940.        --  Cairo.Font_Options.Get_<feature_Name>, like

1941.        --  Cairo.Font_Options.Set_Antialias and

1942.        --  Cairo.Font_Options.Get_Antialias.

1943.        --

1944.        --  New features may be added to a Cairo_font_options in the

1945.        --  future.  For this reason, Cairo.Font_Options.Copy,

1946.        --  Cairo.Font_Options.Equal, Cairo.Font_Options.Merge, and

1947.        --  Cairo.Font_Options.Hash should be used to copy, check

1948.        --  for equality, merge, or compute a hash value of

1949.        --  Cairo_Font_Options objects.

1951.        --  This interface is for dealing with text as text, not caring about the

1952.        --  font object inside the the Cairo_Context.

1954.        procedure Select_Font_FaceTo API docTo body

1955.          (Cr     : Cairo_ContextTo API docTo spec;

1956.           Family : String;

1957.           SlantTo API docTo body  : Cairo_Font_SlantTo API docTo spec;

1958.           WeightTo API docTo body : Cairo_Font_WeightTo API docTo spec);

1959.        --  Cr: a Cairo_Context

1960.        --  Family: a font Family name, encoded in UTF-8

1961.        --  Slant: the Slant for the font

1962.        --  Weight: the Weight for the font

1963.        --

1964.        --  Note: The Select_Font_Face function call is part of what

1965.        --  the cairo designers call the "toy" text API. It is convenient for

1966.        --  short demos and simple programs, but it is not expected to be

1967.        --  adequate for serious text-using applications.

1968.        --

1969.        --  Selects a family and style of font from a simplified description as

1970.        --  a family name, slant and weight. Cairo provides no operation to

1971.        --  list available family names on the system (this is a "toy",

1972.        --  remember), but the standard CSS2 generic family names, ("serif",

1973.        --  "sans-serif", "cursive", "fantasy", "monospace"), are likely to

1974.        --  work as expected.

1975.        --

1976.        --  It is expected that most applications will need to use a more

1977.        --  comprehensive font handling and text layout library, (for example,

1978.        --  pango), in conjunction with cairo.

1979.        --

1980.        --  If text is drawn without a call to Select_Font_Face, (nor

1981.        --  Set_Font_Face nor Set_Scaled_Font), the default

1982.        --  family is platform-specific, but is essentially "sans-serif".

1983.        --  Default slant is Cairo_Font_Slant_Normal, and default weight is

1984.        --  Cairo_Font_Weight_Normal.

1985.        --

1986.        --  This function is equivalent to a call to

1987.        --  Cairo.Font_Face.Toy_Font_Face_Create followed by Set_Font_Face.

1989.        procedure Set_Font_SizeTo API docTo body (Cr : Cairo_ContextTo API docTo spec; Size : GdoubleTo API docTo spec);

1990.        --  Cr: a Cairo_Context

1991.        --  Size: the new font Size, in user space units

1992.        --

1993.        --  Sets the current font matrix to a scale by a factor of size, replacing

1994.        --  any font matrix previously set with Set_Font_Size or

1995.        --  Set_Font_Matrix. This results in a font size of size user space

1996.        --  units. (More precisely, this matrix will result in the font's

1997.        --  em-square being a size by size square in user space.)

1998.        --

1999.        --  If text is drawn without a call to Set_Font_Size, (nor Set_Font_Matrix

2000.        --  nor Set_Scaled_Font), the default font size is 10.0.

2002.        procedure Set_Font_MatrixTo API docTo body

2003.          (Cr     : Cairo_ContextTo API docTo spec;

2004.           Matrix : access Cairo_MatrixTo API docTo spec);

2005.        --  Cr: a Cairo_Context

2006.        --  Matrix: a Cairo_Matrix describing a transform to be applied to

2007.        --  the current font.

2008.        --

2009.        --  Sets the current font matrix to matrix. The font matrix gives a

2010.        --  transformation from the design space of the font (in this space,

2011.        --  the em-square is 1 unit by 1 unit) to user space. Normally, a

2012.        --  simple scale is used (see Set_Font_Size), but a more

2013.        --  complex font matrix can be used to shear the font

2014.        --  or stretch it unequally along the two axes

2016.        procedure Get_Font_MatrixTo API docTo body

2017.          (Cr     : Cairo_ContextTo API docTo spec;

2018.           Matrix : access Cairo_MatrixTo API docTo spec);

2019.        --  Cr: a Cairo_Context

2020.        --  Matrix: return value for the Matrix

2021.        --

2022.        --  Stores the current font matrix into matrix. See Set_Font_Matrix.

2024.        procedure Set_Font_OptionsTo API docTo body

2025.          (Cr      : Cairo_ContextTo API docTo spec;

2026.           Options : Cairo_Font_OptionsTo API docTo spec);

2027.        --  Cr: a Cairo_Context

2028.        --  Options: font Options to use

2029.        --

2030.        --  Sets a set of custom font rendering options for the Cairo_Context.

2031.        --  Rendering options are derived by merging these options with the

2032.        --  options derived from underlying surface; if the value in options

2033.        --  has a default value (like Cairo_Antialias_Default), then the value

2034.        --  from the surface is used.

2036.        procedure Get_Font_OptionsTo API docTo body

2037.          (Cr      : Cairo_ContextTo API docTo spec;

2038.           Options : Cairo_Font_OptionsTo API docTo spec);

2039.        --  Cr: a Cairo_Context

2040.        --  Options: a Cairo_Font_Options object into which to store

2041.        --    the retrieved options. All existing values are overwritten

2042.        --

2043.        --  Retrieves font rendering options set via Set_Font_Options.

2044.        --  Note that the returned options do not include any options derived

2045.        --  from the underlying surface; they are literally the options

2046.        --  passed to Set_Font_Options.

2048.        procedure Set_Font_FaceTo API docTo body

2049.          (Cr        : Cairo_ContextTo API docTo spec;

2050.           Font_Face : Cairo_Font_FaceTo API docTo spec);

2051.        --  Cr: a Cairo_Context

2052.        --  Font_Face: a Cairo_Font_Face, or Null_Font_Face to restore to the

2053.        --  default font

2054.        --

2055.        --  Replaces the current Cairo_Font_Face object in the Cairo_Context with

2056.        --  font_face. The replaced font face in the Cairo_Context will be

2057.        --  destroyed if there are no other references to it.

2059.        function Get_Font_FaceTo API docTo body (Cr : Cairo_ContextTo API docTo spec) return Cairo_Font_FaceTo API docTo spec;

2060.        --  Cr: a Cairo_Context

2061.        --

2062.        --  Gets the current font face for a Cairo_Context.

2063.        --

2064.        --  Return value: the current font face.  This object is owned by

2065.        --  cairo. To keep a reference to it, you must call

2066.        --  Cairo.Font_Face.Reference.

2067.        --

2068.        --  This function never returns Null_Font_Face. If memory cannot be

2069.        --  allocated, a special "nil" Cairo_Font_Face object will be returned on

2070.        --  which Cairo.Font_Face.Status returns Cairo_Status_No_Memory. Using this

2071.        --  nil object will cause its error state to propagate to other objects it

2072.        --  is passed to, (for example, calling Set_Font_Face with a nil font

2073.        --  will trigger an error that will shutdown the Cairo_Context object).

2075.        procedure Set_Scaled_FontTo API docTo body

2076.          (Cr          : Cairo_ContextTo API docTo spec;

2077.           Scaled_Font : access Cairo_Scaled_FontTo API docTo spec);

2078.        --  Cr: a Cairo_Context

2079.        --  Scaled_Font: a Cairo_Scaled_Font

2080.        --

2081.        --  Replaces the current font face, font matrix, and font options in

2082.        --  the Cairo_Context with those of the Cairo_Scaled_Font.  Except for

2083.        --  some translation, the current CTM of the Cairo_Context should be the

2084.        --  same as that of the Cairo_Scaled_Font, which can be accessed

2085.        --  using Cairo.Scaled_Font.Get_Ctm.

2086.        --

2087.        --  Since: 1.2

2089.        function Get_Scaled_FontTo API docTo body (Cr : Cairo_ContextTo API docTo spec) return Cairo_Scaled_FontTo API docTo spec;

2090.        --  Cr: a Cairo_Context

2091.        --

2092.        --  Gets the current scaled font for a Cairo_Context.

2093.        --

2094.        --  Return value: the current scaled font. This object is owned by

2095.        --  cairo. To keep a reference to it, you must call

2096.        --  Cairo.Scaled_Font.Reference.

2097.        --

2098.        --  This function never returns Null_Font_Face. If memory cannot be

2099.        --  allocated, a special "nil" Cairo_Scaled_Font object will be returned on

2100.        --  which Cairo.Font_Face.Status returns Cairo_Status_No_Memory. Using this

2101.        --  nil object will cause its error state to propagate to other objects it

2102.        --  is passed to, (for example, calling Set_Font_Face with a nil font

2103.        --  will trigger an error that will shutdown the Cairo_Context object).

2104.        --

2105.        --  Since: 1.4

2107.        procedure Show_TextTo API docTo body

2108.          (Cr   : Cairo_ContextTo API docTo spec;

2109.           Utf8 : String);

2110.        --  Cr: a cairo context

2111.        --  Utf8: a NUL-terminated string of text encoded in UTF-8, or Null_Ptr

2112.        --

2113.        --  A drawing operator that generates the shape from a string of UTF-8

2114.        --  characters, rendered according to the current Font_Face, Font_Size

2115.        --  (Font_Matrix), and Font_Options.

2116.        --

2117.        --  This function first computes a set of glyphs for the string of

2118.        --  text. The first glyph is placed so that its origin is at the

2119.        --  current point. The origin of each subsequent glyph is offset from

2120.        --  that of the previous glyph by the advance values of the previous

2121.        --  glyph.

2122.        --

2123.        --  After this call the current point is moved to the origin of where

2124.        --  the next glyph would be placed in this same progression. That is,

2125.        --  the current point will be at the origin of the final glyph offset

2126.        --  by its advance values. This allows for easy display of a single

2127.        --  logical string with multiple calls to Show_Text.

2128.        --

2129.        --  Note: The Show_Text function call is part of what the cairo

2130.        --  designers call the "toy" text API. It is convenient for short demos

2131.        --  and simple programs, but it is not expected to be adequate for

2132.        --  serious text-using applications. See Show_Glyphs for the

2133.        --  "real" text display API in cairo.

2135.        procedure Show_GlyphsTo API docTo body

2136.          (Cr         : Cairo_ContextTo API docTo spec;

2137.           Glyphs     : access Cairo_GlyphTo API docTo spec;

2138.           Num_Glyphs : GintTo API docTo spec);

2139.        --  Cr: a cairo context

2140.        --  Glyphs: array of Glyphs to show

2141.        --  Num_Glyphs: number of glyphs to show

2142.        --

2143.        --  A drawing operator that generates the shape from an array of glyphs,

2144.        --  rendered according to the current font face, font size

2145.        --  (font matrix), and font options.

2147.        procedure Text_PathTo API docTo body

2148.          (Cr   : Cairo_ContextTo API docTo spec;

2149.           Utf8 : String);

2150.        --  Cr: a cairo context

2151.        --  Utf8: a NUL-terminated string of text encoded in UTF-8, or Null_Ptr

2152.        --

2153.        --  Adds closed paths for text to the current path.  The generated

2154.        --  path if filled, achieves an effect similar to that of

2155.        --  Show_Text.

2156.        --

2157.        --  Text conversion and positioning is done similar to Show_Text.

2158.        --

2159.        --  Like Show_Text, After this call the current point is

2160.        --  moved to the origin of where the next glyph would be placed in

2161.        --  this same progression.  That is, the current point will be at

2162.        --  the origin of the final glyph offset by its advance values.

2163.        --  This allows for chaining multiple calls to to Cairo_Text_Path

2164.        --  without having to set current point in between.

2165.        --

2166.        --  Note: The Text_Path function call is part of what the cairo

2167.        --  designers call the "toy" text API. It is convenient for short demos

2168.        --  and simple programs, but it is not expected to be adequate for

2169.        --  serious text-using applications. See Glyph_Path for the

2170.        --  "real" text path API in cairo.

2172.        procedure Text_ExtentsTo API docTo body

2173.          (Cr      : Cairo_ContextTo API docTo spec;

2174.           Utf8    : Interfaces.C.Strings.chars_ptr;

2175.           Extents : access Cairo_Text_ExtentsTo API docTo spec);

2176.        --  Cr: a Cairo_Context

2177.        --  Utf8: a NUL-terminated string of text encoded in UTF-8, or Null_Ptr

2178.        --  Extents: a Cairo_Text_Extents object into which the results

2179.        --  will be stored

2180.        --

2181.        --  Gets the extents for a string of text. The extents describe a

2182.        --  user-space rectangle that encloses the "inked" portion of the text,

2183.        --  (as it would be drawn by Show_Text). Additionally, the

2184.        --  x_advance and y_advance values indicate the amount by which the

2185.        --  current point would be advanced by Cairo_Show_Text.

2186.        --

2187.        --  Note that whitespace characters do not directly contribute to the

2188.        --  size of the rectangle (extents.width and extents.height). They do

2189.        --  contribute indirectly by changing the position of non-whitespace

2190.        --  characters. In particular, trailing whitespace characters are

2191.        --  likely to not affect the size of the rectangle, though they will

2192.        --  affect the x_advance and y_advance values.

2194.        procedure Glyph_ExtentsTo API docTo body

2195.          (Cr         : Cairo_ContextTo API docTo spec;

2196.           Glyphs     : access Cairo_GlyphTo API docTo spec;

2197.           Num_Glyphs : GintTo API docTo spec;

2198.           Extents    : access Cairo_Text_ExtentsTo API docTo spec);

2199.        --  Cr: a Cairo_Context

2200.        --  Glyphs: an array of Cairo_Glyph objects

2201.        --  Num_Glyphs: the number of elements in glyphs

2202.        --  Extents: a Cairo_Text_Extents object into which the results

2203.        --  will be stored

2204.        --

2205.        --  Gets the extents for an array of glyphs. The extents describe a

2206.        --  user-space rectangle that encloses the "inked" portion of the

2207.        --  glyphs, (as they would be drawn by Show_Glyphs).

2208.        --  Additionally, the X_Advance and Y_Advance values indicate the

2209.        --  amount by which the current point would be advanced by

2210.        --  Show_Glyphs.

2211.        --

2212.        --  Note that whitespace glyphs do not contribute to the size of the

2213.        --  rectangle (Extents.Width and Extents.Height).

2215.        procedure Font_ExtentsTo API docTo body

2216.          (Cr      : Cairo_ContextTo API docTo spec;

2217.           Extents : access Cairo_Font_ExtentsTo API docTo spec);

2218.        --  Cr: a Cairo_Context

2219.        --  Extents: a Cairo_Font_Extents object into which the results

2220.        --  will be stored.

2221.        --

2222.        --  Gets the font extents for the currently selected font.

2224.        type Cairo_Font_Type is

2225.          (Cairo_Font_Type_Toy,

2226.           --  The font was created using cairo's toy font api (Since: 1.8)

2228.           Cairo_Font_Type_Ft,

2229.           --  The font is of type FreeType

2231.           Cairo_Font_Type_Win32,

2232.           --  The font is of type Win32

2234.           Cairo_Font_Type_Quartz,

2235.           --  The font is of type Quartz (Since: 1.6)

2237.           Cairo_Font_Type_User

2238.           --  The font was create using cairo's user font api

2239.          );

2240.        --  Cairo_font_type is used to describe the type of a given font

2241.        --  face or scaled font. The font types are also known as "font

2242.        --  backends" within Cairo.

2243.        --

2244.        --  The type of a font face is determined by the function used to

2245.        --  create it, which will generally be of the form

2246.        --  <type>_Font_Face_Create. The font face type

2247.        --  can be queried

2248.        --  with Cairo.Font_Face.Get_Type

2249.        --

2250.        --  The various Cairo_Font_Face functions can be used with a font face

2251.        --  of any type.

2252.        --

2253.        --  The type of a scaled font is determined by the type of the font

2254.        --  face passed to Cairo.Scaled_Font.Create. The scaled font type can

2255.        --  be queried with Cairo.Scaled_Font.Get_Type

2256.        --

2257.        --  The various Cairo_scaled_font functions can be used with scaled

2258.        --  fonts of any type, but some font backends also provide

2259.        --  type-specific functions that must only be called with a scaled font

2260.        --  of the appropriate type. These functions have names that begin with

2261.        --  <type>_Scaled_Font such as Ft_Scaled_Font_Lock_Face.

2262.        --

2263.        --  The behavior of calling a type-specific function with a scaled font

2264.        --  of the wrong type is undefined.

2265.        --

2266.        --  New entries may be added in future versions.

2267.        --

2268.        --  Since: 1.2

2269.        pragma Convention (C, Cairo_Font_TypeTo API docTo spec);

2271.        ---------------------

2272.        -- Query functions --

2273.        ---------------------

2275.        function Get_OperatorTo API docTo body (Cr : Cairo_ContextTo API docTo spec) return Cairo_OperatorTo API docTo spec;

2276.        --  Cr: a cairo context

2277.        --

2278.        --  Gets the current compositing operator for a cairo context.

2279.        --

2280.        --  Return value: the current compositing operator.

2282.        function Get_SourceTo API docTo body (Cr : Cairo_ContextTo API docTo spec) return Cairo_PatternTo API docTo spec;

2283.        --  Cr: a cairo context

2284.        --

2285.        --  Gets the current source pattern for Cr.

2286.        --

2287.        --  Return value: the current source pattern. This object is owned by

2288.        --  cairo. To keep a reference to it, you must call

2289.        --  Cairo.Pattern.Reference.

2291.        function Get_ToleranceTo API docTo body (Cr : Cairo_ContextTo API docTo spec) return GdoubleTo API docTo spec;

2292.        --  Cr: a cairo context

2293.        --

2294.        --  Gets the current tolerance value, as set by Set_Tolerance.

2295.        --

2296.        --  Return value: the current tolerance value.

2298.        function Get_AntialiasTo API docTo body (Cr : Cairo_ContextTo API docTo spec) return Cairo_AntialiasTo API docTo spec;

2299.        --  Cr: a cairo context

2300.        --

2301.        --  Gets the current shape antialiasing mode, as set by Set_Antialias.

2302.        --

2303.        --  Return value: the current shape antialiasing mode.

2305.        function Has_Current_PointTo API docTo body (Cr : Cairo_ContextTo API docTo spec) return Cairo_BoolTo API docTo spec;

2306.        --  Cr: a cairo context

2307.        --

2308.        --  Returns whether a current point is defined on the current path.

2309.        --  See Get_Current_Point for details on the current point.

2310.        --

2311.        --  Return value: whether a current point is defined.

2312.        --

2313.        --  Since: 1.6

2315.        procedure Get_Current_PointTo API docTo body

2316.          (Cr : Cairo_ContextTo API docTo spec;

2317.           X  : access GdoubleTo API docTo spec;

2318.           Y  : access GdoubleTo API docTo spec);

2319.        --  Cr: a cairo context

2320.        --  X: return value for X coordinate of the current point

2321.        --  Y: return value for Y coordinate of the current point

2322.        --

2323.        --  Gets the current point of the current path, which is

2324.        --  conceptually the final point reached by the path so far.

2325.        --

2326.        --  The current point is returned in the user-space coordinate

2327.        --  system. If there is no defined current point or if cr is in an

2328.        --  error status, X and Y will both be set to 0.0. It is possible to

2329.        --  check this in advance with Has_Current_Point.

2330.        --

2331.        --  Most path construction functions alter the current point. See the

2332.        --  following for details on how they affect the current point:

2333.        --  New_Path, New_Sub_Path, Append_Path, Close_Path, Move_To, Line_To,

2334.        --  Curve_To, Rel_Move_To, Rel_Line_To, Rel_Curve_To, Arc, Arc_Negative,

2335.        --  Rectangle, Text_Path, Glyph_Path, Stroke_To_Path.

2336.        --

2337.        --  Some functions use and alter the current point but do not otherwise

2338.        --  change current path: Show_Text.

2339.        --

2340.        --  Some functions unset the current path and as a result, current point:

2341.        --  Fill, Stroke.

2343.        function Get_Fill_RuleTo API docTo body (Cr : Cairo_ContextTo API docTo spec) return Cairo_Fill_RuleTo API docTo spec;

2344.        --  Cr: a cairo context

2345.        --

2346.        --  Gets the current fill rule, as set by Set_Fill_Rule.

2347.        --

2348.        --  Return value: the current fill rule.

2350.        function Get_Line_WidthTo API docTo body (Cr : Cairo_ContextTo API docTo spec) return GdoubleTo API docTo spec;

2351.        --  Cr: a cairo context

2352.        --

2353.        --  This function returns the current line width value exactly as set by

2354.        --  Set_Line_Width. Note that the value is unchanged even if

2355.        --  the CTM has changed between the calls to Set_Line_Width and

2356.        --  Get_Line_Width.

2357.        --

2358.        --  Return value: the current line width.

2360.        function Get_Line_CapTo API docTo body (Cr : Cairo_ContextTo API docTo spec) return Cairo_Line_CapTo API docTo spec;

2361.        --  Cr: a cairo context

2362.        --

2363.        --  Gets the current line cap style, as set by Set_Line_Cap.

2364.        --

2365.        --  Return value: the current line cap style.

2367.        function Get_Line_JoinTo API docTo body (Cr : Cairo_ContextTo API docTo spec) return Cairo_Line_JoinTo API docTo spec;

2368.        --  Cr: a cairo context

2369.        --

2370.        --  Gets the current line join style, as set by Set_Line_Join.

2371.        --

2372.        --  Return value: the current line join style.

2374.        function Get_Miter_LimitTo API docTo body (Cr : Cairo_ContextTo API docTo spec) return GdoubleTo API docTo spec;

2375.        --  Cr: a cairo context

2376.        --

2377.        --  Gets the current miter limit, as set by Set_Miter_Limit.

2378.        --

2379.        --  Return value: the current miter limit.

2381.        function Get_Dash_CountTo API docTo body (Cr : Cairo_ContextTo API docTo spec) return GintTo API docTo spec;

2382.        --  Cr: a Cairo_Context

2383.        --

2384.        --  This function returns the length of the dash array in cr (0 if dashing

2385.        --  is not currently in effect).

2386.        --

2387.        --  See also Set_Dash and Get_Dash.

2388.        --

2389.        --  Return value: the length of the dash array, or 0 if no dash array set.

2390.        --

2391.        --  Since: 1.4

2393.        type Dash_Array_Access is access all Dash_ArrayTo API docTo spec;

2395.        procedure Get_DashTo API docTo body

2396.          (Cr     : Cairo_ContextTo API docTo spec;

2397.           Dashes : out Dash_Array_AccessTo API docTo spec;

2398.           Offset : out GdoubleTo API docTo spec);

2399.        --  Cr: a Cairo_Context

2400.        --  Dashes: return value for the dash array, or null

2401.        --  Offset: return value for the current dash Offset, or null

2402.        --

2403.        --  Gets the current dash array.

2404.        --

2405.        --  Since: 1.4

2407.        procedure Get_MatrixTo API docTo body (Cr : Cairo_ContextTo API docTo spec; Matrix : access Cairo_MatrixTo API docTo spec);

2408.        --  Cr: a cairo context

2409.        --  Matrix: return value for the Matrix

2410.        --

2411.        --  Stores the current transformation matrix (CTM) into matrix.

2413.        function Get_TargetTo API docTo body (Cr : Cairo_ContextTo API docTo spec) return Cairo_SurfaceTo API docTo spec;

2414.        --  Cr: a cairo context

2415.        --

2416.        --  Gets the target surface for the cairo context as passed to Create.

2417.        --

2418.        --  This function will always return a valid pointer, but the result

2419.        --  can be a "nil" surface if cr is already in an error state,

2420.        --  (ie. Cairo_Status /= Cairo_Status_Success).

2421.        --  A nil surface is indicated by

2422.        --  Cairo.Surface.Status/= Cairo_Status_Success.

2423.        --

2424.        --  Return value: the target surface. This object is owned by cairo. To

2425.        --  keep a reference to it, you must call Cairo.Surface.Reference.

2427.        function Get_Group_TargetTo API docTo body (Cr : Cairo_ContextTo API docTo spec) return Cairo_SurfaceTo API docTo spec;

2428.        --  Cr: a cairo context

2429.        --

2430.        --  Gets the current destination surface for the context. This is either

2431.        --  the original target surface as passed to Create or the target

2432.        --  surface for the current group as started by the most recent call to

2433.        --  Push_Group or Push_Group_With_Content.

2434.        --

2435.        --  This function will always return a valid pointer, but the result

2436.        --  can be a "nil" surface if cr is already in an error state,

2437.        --  (ie. Cairo_Status /= Cairo_Status_Success).

2438.        --  A nil surface is indicated by Cairo_Status /= Cairo_Status_Success.

2439.        --

2440.        --  Return value: the target surface. This object is owned by cairo. To

2441.        --  keep a reference to it, you must call Cairo.Surface.Reference.

2442.        --

2443.        --  Since: 1.2

2445.        type Cairo_Path_Data_Type is

2446.          (Cairo_Path_Move_To,    --  A move-to operation

2447.           Cairo_Path_Line_To,    --  A line-to operation

2448.           Cairo_Path_Curve_To,   --  A curve-to operation

2449.           Cairo_Path_Close_Path  --  A close-path operation

2450.          );

2451.        --  Cairo_path_data is used to describe the type of one portion

2452.        --  of a path when represented as a Cairo_Path.

2453.        --  See Cairo_Path_Data for details.

2454.        pragma Convention (C, Cairo_Path_Data_TypeTo API docTo spec);

2456.        type Header_Type is record

2457.           Path_Type : aliased Cairo_Path_Data_TypeTo API docTo spec;

2458.           Length    : aliased GintTo API docTo spec;

2459.        end record;

2460.        --  A Path header. See Cairo_Path_Data for details.

2462.        type Point_Type is record

2463.           X : aliased GdoubleTo API docTo spec;

2464.           Y : aliased GdoubleTo API docTo spec;

2465.        end record;

2466.        --  A geometrical point. See Cairo_Path_Data for details.

2468.        type Cairo_Path_Data (Discr : GuintTo API docTo spec := 0) is record

2469.           case Discr is

2470.              when 0 =>

2471.                 Header : aliased Header_TypeTo API docTo spec;

2472.              when others =>

2473.                 Point : aliased Point_TypeTo API docTo spec;

2474.           end case;

2475.        end record;

2476.        --  Cairo_path_data is used to represent the path data inside a

2477.        --  Cairo_path.

2478.        --

2479.        --  The data structure is designed to try to balance the demands of

2480.        --  efficiency and ease-of-use. A path is represented as an array of

2481.        --  Cairo_Path_Data, which is a union of headers and points.

2482.        --

2483.        --  Each portion of the path is represented by one or more elements in

2484.        --  the array, (one header followed by 0 or more points). The length

2485.        --  value of the header is the number of array elements for the current

2486.        --  portion including the header, (ie. length == 1 +  of points), and

2487.        --  where the number of points for each element type is as follows:

2488.        --

2489.        --      Cairo_Path_Move_To:     1 point

2490.        --      Cairo_Path_Line_To:     1 point

2491.        --      Cairo_Path_Curve_To:    3 points

2492.        --      Cairo_Path_Close_Path:  0 points

2493.        --

2494.        --  The semantics and ordering of the coordinate values are consistent

2495.        --  with Move_To, Line_To, Curve_To, and Close_Path.

2496.        --

2497.        --  Here is sample code for iterating through a Cairo_Path:

2498.        --

2499.        --    declare

2500.        --       J    : Gint;

2501.        --       Path : Cairo_Path;

2502.        --       Data : Cairo_Path_Data;

2503.        --     begin

2504.        --       Path = Copy_Path (Cr);

2505.        --

2506.        --       J := 0;

2507.        --       while J < Path.Num_Data loop

2508.        --          Data := Path.Data(J);

2509.        --

2510.        --          case Data.Header.Path_Type is

2511.        --

2512.        --              when Cairo_Path_Move_To =>

2513.        --                 Do_Move_To_Things (Data(1).Point.X, Data(1).Point.Y);

2514.        --

2515.        --              when Cairo_Path_Line_To =>

2516.        --                 Do_Line_To_Things (Data(1).Point.X, Data(1).Point.Y);

2517.        --

2518.        --              when Cairo_Path_Curve_To =>

2519.        --                 Do_Curve_To_Things (Data(1).Point.X, Data(1).Point.Y,

2520.        --                                     Data(2).Point.X, Data(2).Point.Y,

2521.        --                                     Data(3).Point.X, Data(3).Point.Y);

2522.        --

2523.        --              when Cairo_Path_Curve_To =>

2524.        --                 Do_Close_Path_Things;

2525.        --          end case;

2526.        --

2527.        --          J := J + Path.Data[J].Header.Length;

2528.        --       end loop;

2529.        --

2530.        --       Path_Destroy (Path);

2531.        --    end;

2532.        --

2533.        --  As of cairo 1.4, cairo does not mind if there are more elements in

2534.        --  a portion of the path than needed.  Such elements can be used by

2535.        --  users of the cairo API to hold extra values in the path data

2536.        --  structure.  For this reason, it is recommended that applications

2537.        --  always use Data.Header.Length to iterate over the path data, instead of

2538.        --  hardcoding the number of elements for each element type.

2540.        type Path_Data_Array is array (Natural) of Cairo_Path_DataTo API docTo spec;

2541.        type Path_Data_Array_Access is access all Path_Data_ArrayTo API docTo spec;

2543.        type Cairo_Path is record

2544.           Status   : aliased Cairo_StatusTo API docTo spec;

2545.           Data     : Path_Data_Array_AccessTo API docTo spec;

2546.           --  Warning: for efficiency reasons, Data is a direct mapping to the C

2547.           --  structure. Therefore, there is no bounds checking on this array,

2548.           --  the user needs to make sure only to access data between indexes

2549.           --  0 and Num_Data-1.

2550.           Num_Data : aliased GintTo API docTo spec;

2551.        end record;

2552.        type Cairo_Path_Access is access all Cairo_PathTo API docTo spec;

2553.        --  Status: the current error Status

2554.        --  Data: the elements in the path

2555.        --  Num_Data: the number of elements in the data array

2556.        --

2557.        --  A data structure for holding a path. This data structure serves as the

2558.        --  return value for Copy_Path and Copy_Path_Flat as well the input value

2559.        --  for Append_Path.

2560.        --

2561.        --  See Cairo_Path_Data for hints on how to iterate over the

2562.        --  actual data within the path.

2563.        --

2564.        --  The num_data member gives the number of elements in the data

2565.        --  array. This number is larger than the number of independent path

2566.        --  portions (defined in Cairo_Path_Data_Type), since the data

2567.        --  includes both headers and coordinates for each portion.

2569.        function Copy_PathTo API docTo body (Cr : Cairo_ContextTo API docTo spec) return Cairo_Path_AccessTo API docTo spec;

2570.        --  Cr: a cairo context

2571.        --

2572.        --  Creates a copy of the current path and returns it to the user as a

2573.        --  Cairo_Path. See Cairo_Path_Data for hints on how to iterate

2574.        --  over the returned data structure.

2575.        --

2576.        --  This function will always return a valid pointer, but the result

2577.        --  will have no data (Data = null and Num_Data = 0), if

2578.        --  either of the following conditions hold:

2579.        --

2580.        --  -> If there is insufficient memory to copy the path. In this

2581.        --      case Path.Status will be set to Cairo_Status_No_Memory

2582.        --

2583.        --  -> If Cr is already in an error state. In this case

2584.        --     Path.Status will contain the same status that

2585.        --     would be returned by Status.

2586.        --

2587.        --  Return value: the copy of the current path. The caller owns the

2588.        --  returned object and should call Path_Destroy when finished with it.

2590.        function Copy_Path_FlatTo API docTo body (Cr : Cairo_ContextTo API docTo spec) return Cairo_Path_AccessTo API docTo spec;

2591.        --  Cr: a cairo context

2592.        --

2593.        --  Gets a flattened copy of the current path and returns it to the

2594.        --  user as a Cairo_Path. See Cairo_Path_Data for hints on

2595.        --  how to iterate over the returned data structure.

2596.        --

2597.        --  This function is like Copy_Path except that any curves

2598.        --  in the path will be approximated with piecewise-linear

2599.        --  approximations, (accurate to within the current tolerance

2600.        --  value). That is, the result is guaranteed to not have any elements

2601.        --  of type Cairo_Path_Curve_To which will instead be replaced by a

2602.        --  series of Cairo_Path_Line_To elements.

2603.        --

2604.        --  This function will always return a valid pointer, but the result will

2605.        --  have no data (Data = null and Num_Data = 0), if either of the following

2606.        --  conditions hold:

2607.        --

2608.        --  -> If there is insufficient memory to copy the path. In this

2609.        --      case Path.Status will be set to Cairo_Status_No_Memory

2610.        --

2611.        --  -> If Cr is already in an error state. In this case

2612.        --     Path.Status will contain the same status that

2613.        --     would be returned by Status.

2614.        --

2615.        --  Return value: the copy of the current path. The caller owns the

2616.        --  returned object and should call Path_Destroy when finished

2617.        --  with it.

2619.        procedure Append_PathTo API docTo body

2620.          (Cr   : Cairo_ContextTo API docTo spec;

2621.           Path : access Cairo_PathTo API docTo spec);

2622.        --  Cr: a cairo context

2623.        --  Path: Path to be appended

2624.        --

2625.        --  Append the path onto the current path. The path may be either the return

2626.        --  value from one of Copy_Path or Copy_Path_Flat or it may be constructed

2627.        --  manually. See Cairo_Path for details on how the path data structure

2628.        --  should be initialized, and note that Path.Status must be initialized to

2629.        --  Cairo_Status_Success.

2631.        procedure Path_DestroyTo API docTo body (Path : access Cairo_PathTo API docTo spec);

2632.        --  Path: a path previously returned by either Copy_Path or Copy_Path_Flat.

2633.        --

2634.        --  Immediately releases all memory associated with Path. After a call

2635.        --  to Path_Destroy the Path pointer is no longer valid and should not be

2636.        --  used further.

2637.        --

2638.        --  Note: Path_Destroy should only be called with an access to a

2639.        --  Cairo_Path returned by a cairo function. Any path that is created

2640.        --  manually (ie. outside of cairo) should be destroyed manually as well.

2642.        --------------------------

2643.        -- Error status queries --

2644.        --------------------------

2646.        function StatusTo API docTo body (Cr : Cairo_ContextTo API docTo spec) return Cairo_StatusTo API docTo spec;

2647.        --  Cr: a cairo context

2648.        --

2649.        --  Checks whether an error has previously occurred for this context.

2650.        --

2651.        --  Returns: the current status of this context, see Cairo_Status

2653.        Null_Context      : constant Cairo_ContextTo API docTo spec;

2654.        Null_Surface      : constant Cairo_SurfaceTo API docTo spec;

2655.        Null_Pattern      : constant Cairo_PatternTo API docTo spec;

2656.        Null_Scaled_Font  : constant Cairo_Scaled_FontTo API docTo spec;

2657.        Null_Font_Face    : constant Cairo_Font_FaceTo API docTo spec;

2658.        Null_Font_Options : constant Cairo_Font_OptionsTo API docTo spec;

2660.     private

2662.        pragma Convention (C, Cairo_Destroy_FuncTo API docTo spec);

2663.        pragma Convention (C, Cairo_BoolTo API docTo spec);

2664.        pragma Convention (C, Cairo_StatusTo API docTo spec);

2665.        pragma Convention (C, Cairo_OperatorTo API docTo spec);

2666.        pragma Convention (C, Cairo_AntialiasTo API docTo spec);

2667.        pragma Convention (C, Cairo_Fill_RuleTo API docTo spec);

2668.        pragma Convention (C, Cairo_Line_CapTo API docTo spec);

2669.        pragma Convention (C, Cairo_Line_JoinTo API docTo spec);

2670.        pragma Convention (C, Path_Data_Array_AccessTo API docTo spec);

2671.        pragma Convention (C_Pass_By_Copy, Cairo_PathTo API docTo spec);

2672.        pragma Convention (C_Pass_By_Copy, Cairo_RectangleTo API docTo spec);

2673.        pragma Convention (C, Cairo_Rectangle_Array_AccessTo API docTo spec);

2675.        pragma Convention (C_Pass_By_Copy, Header_TypeTo API docTo spec);

2676.        pragma Convention (C_Pass_By_Copy, Point_TypeTo API docTo spec);

2677.        pragma Convention (C_Pass_By_Copy, Cairo_Path_DataTo API docTo spec);

2678.        pragma Unchecked_Union (Cairo_Path_DataTo API docTo spec);

2680.        type Cairo_ContextTo API docTo spec is new System.Address;

2681.        Null_ContextTo API docTo spec : constant Cairo_ContextTo API docTo spec :=

2682.          Cairo_ContextTo API docTo spec (System.Null_Address);

2683.        type Cairo_SurfaceTo API docTo spec is new System.Address;

2684.        Null_SurfaceTo API docTo spec : constant Cairo_SurfaceTo API docTo spec :=

2685.          Cairo_SurfaceTo API docTo spec (System.Null_Address);

2686.        type Cairo_PatternTo API docTo spec is new System.Address;

2687.        Null_PatternTo API docTo spec : constant Cairo_PatternTo API docTo spec :=

2688.          Cairo_PatternTo API docTo spec (System.Null_Address);

2689.        type Cairo_Scaled_FontTo API docTo spec is new System.Address;

2690.        Null_Scaled_FontTo API docTo spec : constant Cairo_Scaled_FontTo API docTo spec :=

2691.          Cairo_Scaled_FontTo API docTo spec (System.Null_Address);

2692.        type Cairo_Font_FaceTo API docTo spec is new System.Address;

2693.        Null_Font_FaceTo API docTo spec : constant Cairo_Font_FaceTo API docTo spec :=

2694.          Cairo_Font_FaceTo API docTo spec (System.Null_Address);

2695.        type Cairo_Font_OptionsTo API docTo spec is new System.Address;

2696.        Null_Font_OptionsTo API docTo spec : constant Cairo_Font_OptionsTo API docTo spec :=

2697.          Cairo_Font_OptionsTo API docTo spec (System.Null_Address);

2698.        pragma Import (C, CreateTo API docTo spec, "cairo_create");

2699.        pragma Import (C, ReferenceTo API docTo spec, "cairo_reference");

2700.        pragma Import (C, DestroyTo API docTo spec, "cairo_destroy");

2701.        pragma Import (C, Get_Reference_CountTo API docTo spec, "cairo_get_reference_count");

2702.        pragma Import (C, Get_User_DataTo API docTo spec, "cairo_get_user_data");

2703.        pragma Import (C, Set_User_DataTo API docTo spec, "cairo_set_user_data");

2704.        pragma Import (C, SaveTo API docTo spec, "cairo_save");

2705.        pragma Import (C, RestoreTo API docTo spec, "cairo_restore");

2706.        pragma Import (C, Push_GroupTo API docTo spec, "cairo_push_group");

2707.        pragma Import

2708.          (C,

2709.           Push_Group_With_ContentTo API docTo spec,

2710.           "cairo_push_group_with_content");

2711.        pragma Import (C, Pop_GroupTo API docTo spec, "cairo_pop_group");

2712.        pragma Import (C, Pop_Group_To_SourceTo API docTo spec, "cairo_pop_group_to_source");

2713.        pragma Import (C, Set_OperatorTo API docTo spec, "cairo_set_operator");

2714.        pragma Import (C, Set_SourceTo API docTo spec, "cairo_set_source");

2715.        pragma Import (C, Set_Source_RgbTo API docTo spec, "cairo_set_source_rgb");

2716.        pragma Import (C, Set_Source_RgbaTo API docTo spec, "cairo_set_source_rgba");

2717.        pragma Import (C, Set_Source_SurfaceTo API docTo spec, "cairo_set_source_surface");

2718.        pragma Import (C, Set_ToleranceTo API docTo spec, "cairo_set_tolerance");

2719.        pragma Import (C, Set_AntialiasTo API docTo spec, "cairo_set_antialias");

2720.        pragma Import (C, Set_Fill_RuleTo API docTo spec, "cairo_set_fill_rule");

2721.        pragma Import (C, Set_Line_WidthTo API docTo spec, "cairo_set_line_width");

2722.        pragma Import (C, Set_Line_CapTo API docTo spec, "cairo_set_line_cap");

2723.        pragma Import (C, Set_Line_JoinTo API docTo spec, "cairo_set_line_join");

2724.        pragma Import (C, Set_Miter_LimitTo API docTo spec, "cairo_set_miter_limit");

2725.        pragma Import (C, TranslateTo API docTo spec, "cairo_translate");

2726.        pragma Import (C, ScaleTo API docTo spec, "cairo_scale");

2727.        pragma Import (C, RotateTo API docTo spec, "cairo_rotate");

2728.        pragma Import (C, TransformTo API docTo spec, "cairo_transform");

2729.        pragma Import (C, Set_MatrixTo API docTo spec, "cairo_set_matrix");

2730.        pragma Import (C, Identity_MatrixTo API docTo spec, "cairo_identity_matrix");

2731.        pragma Import (C, User_To_DeviceTo API docTo spec, "cairo_user_to_device");

2732.        pragma Import

2733.          (C,

2734.           User_To_Device_DistanceTo API docTo spec,

2735.           "cairo_user_to_device_distance");

2736.        pragma Import (C, Device_To_UserTo API docTo spec, "cairo_device_to_user");

2737.        pragma Import

2738.          (C,

2739.           Device_To_User_DistanceTo API docTo spec,

2740.           "cairo_device_to_user_distance");

2741.        pragma Import (C, New_PathTo API docTo spec, "cairo_new_path");

2742.        pragma Import (C, Move_ToTo API docTo spec, "cairo_move_to");

2743.        pragma Import (C, New_Sub_PathTo API docTo spec, "cairo_new_sub_path");

2744.        pragma Import (C, Line_ToTo API docTo spec, "cairo_line_to");

2745.        pragma Import (C, Curve_ToTo API docTo spec, "cairo_curve_to");

2746.        pragma Import (C, ArcTo API docTo spec, "cairo_arc");

2747.        pragma Import (C, Arc_NegativeTo API docTo spec, "cairo_arc_negative");

2748.        pragma Import (C, Rel_Move_ToTo API docTo spec, "cairo_rel_move_to");

2749.        pragma Import (C, Rel_Line_ToTo API docTo spec, "cairo_rel_line_to");

2750.        pragma Import (C, Rel_Curve_ToTo API docTo spec, "cairo_rel_curve_to");

2751.        pragma Import (C, RectangleTo API docTo spec, "cairo_rectangle");

2752.        pragma Import (C, Close_PathTo API docTo spec, "cairo_close_path");

2753.        pragma Import (C, Path_ExtentsTo API docTo spec, "cairo_path_extents");

2754.        pragma Import (C, PaintTo API docTo spec, "cairo_paint");

2755.        pragma Import (C, Paint_With_AlphaTo API docTo spec, "cairo_paint_with_alpha");

2756.        pragma Import (C, MaskTo API docTo spec, "cairo_mask");

2757.        pragma Import (C, Mask_SurfaceTo API docTo spec, "cairo_mask_surface");

2758.        pragma Import (C, StrokeTo API docTo spec, "cairo_stroke");

2759.        pragma Import (C, Stroke_PreserveTo API docTo spec, "cairo_stroke_preserve");

2760.        pragma Import (C, FillTo API docTo spec, "cairo_fill");

2761.        pragma Import (C, Fill_PreserveTo API docTo spec, "cairo_fill_preserve");

2762.        pragma Import (C, Copy_PageTo API docTo spec, "cairo_copy_page");

2763.        pragma Import (C, Show_PageTo API docTo spec, "cairo_show_page");

2764.        pragma Import (C, In_StrokeTo API docTo spec, "cairo_in_stroke");

2765.        pragma Import (C, In_FillTo API docTo spec, "cairo_in_fill");

2766.        pragma Import (C, Stroke_ExtentsTo API docTo spec, "cairo_stroke_extents");

2767.        pragma Import (C, Fill_ExtentsTo API docTo spec, "cairo_fill_extents");

2768.        pragma Import (C, Reset_ClipTo API docTo spec, "cairo_reset_clip");

2769.        pragma Import (C, ClipTo API docTo spec, "cairo_clip");

2770.        pragma Import (C, Clip_PreserveTo API docTo spec, "cairo_clip_preserve");

2771.        pragma Import (C, Clip_ExtentsTo API docTo spec, "cairo_clip_extents");

2772.        pragma Import

2773.          (C,

2774.           Copy_Clip_Rectangle_ListTo API docTo spec,

2775.           "cairo_copy_clip_rectangle_list");

2776.        pragma Import (C, Rectangle_List_DestroyTo API docTo spec, "cairo_rectangle_list_destroy");

2777.        pragma Import (C, Set_Font_SizeTo API docTo spec, "cairo_set_font_size");

2778.        pragma Import (C, Set_Font_MatrixTo API docTo spec, "cairo_set_font_matrix");

2779.        pragma Import (C, Get_Font_MatrixTo API docTo spec, "cairo_get_font_matrix");

2780.        pragma Import (C, Set_Font_OptionsTo API docTo spec, "cairo_set_font_options");

2781.        pragma Import (C, Get_Font_OptionsTo API docTo spec, "cairo_get_font_options");

2782.        pragma Import (C, Set_Font_FaceTo API docTo spec, "cairo_set_font_face");

2783.        pragma Import (C, Get_Font_FaceTo API docTo spec, "cairo_get_font_face");

2784.        pragma Import (C, Set_Scaled_FontTo API docTo spec, "cairo_set_scaled_font");

2785.        pragma Import (C, Get_Scaled_FontTo API docTo spec, "cairo_get_scaled_font");

2786.        pragma Import (C, Show_GlyphsTo API docTo spec, "cairo_show_glyphs");

2787.        --     pragma Import (C, Show_Text_Glyphs, "cairo_show_text_glyphs");

2788.        --     pragma Import (C, Glyph_Path, "cairo_glyph_path");

2789.        pragma Import (C, Text_ExtentsTo API docTo spec, "cairo_text_extents");

2790.        pragma Import (C, Glyph_ExtentsTo API docTo spec, "cairo_glyph_extents");

2791.        pragma Import (C, Font_ExtentsTo API docTo spec, "cairo_font_extents");

2792.        pragma Import (C, Get_OperatorTo API docTo spec, "cairo_get_operator");

2793.        pragma Import (C, Get_SourceTo API docTo spec, "cairo_get_source");

2794.        pragma Import (C, Get_ToleranceTo API docTo spec, "cairo_get_tolerance");

2795.        pragma Import (C, Get_AntialiasTo API docTo spec, "cairo_get_antialias");

2796.        pragma Import (C, Has_Current_PointTo API docTo spec, "cairo_has_current_point");

2797.        pragma Import (C, Get_Current_PointTo API docTo spec, "cairo_get_current_point");

2798.        pragma Import (C, Get_Fill_RuleTo API docTo spec, "cairo_get_fill_rule");

2799.        pragma Import (C, Get_Line_WidthTo API docTo spec, "cairo_get_line_width");

2800.        pragma Import (C, Get_Line_CapTo API docTo spec, "cairo_get_line_cap");

2801.        pragma Import (C, Get_Line_JoinTo API docTo spec, "cairo_get_line_join");

2802.        pragma Import (C, Get_Miter_LimitTo API docTo spec, "cairo_get_miter_limit");

2803.        pragma Import (C, Get_Dash_CountTo API docTo spec, "cairo_get_dash_count");

2804.        pragma Import (C, Get_MatrixTo API docTo spec, "cairo_get_matrix");

2805.        pragma Import (C, Get_TargetTo API docTo spec, "cairo_get_target");

2806.        pragma Import (C, Get_Group_TargetTo API docTo spec, "cairo_get_group_target");

2807.        pragma Import (C, Copy_PathTo API docTo spec, "cairo_copy_path");

2808.        pragma Import (C, Copy_Path_FlatTo API docTo spec, "cairo_copy_path_flat");

2809.        pragma Import (C, Append_PathTo API docTo spec, "cairo_append_path");

2810.        pragma Import (C, Path_DestroyTo API docTo spec, "cairo_path_destroy");

2811.        pragma Import (C, StatusTo API docTo spec, "cairo_status");

2813.     end CairoTo API docTo specTo body;