1------------------------------------------------------------------------------
2--                  GtkAda - Ada95 binding for Gtk+/Gnome                   --
3--                                                                          --
4--                     Copyright (C) 2011-2015, AdaCore                     --
5--                                                                          --
6-- This library is free software;  you can redistribute it and/or modify it --
7-- under terms of the  GNU General Public License  as published by the Free --
8-- Software  Foundation;  either version 3,  or (at your  option) any later --
9-- version. This library is distributed in the hope that it will be useful, --
10-- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- --
11-- TABILITY or FITNESS FOR A PARTICULAR PURPOSE.                            --
12--                                                                          --
13-- As a special exception under Section 7 of GPL version 3, you are granted --
14-- additional permissions described in the GCC Runtime Library Exception,   --
15-- version 3.1, as published by the Free Software Foundation.               --
16--                                                                          --
17-- You should have received a copy of the GNU General Public License and    --
18-- a copy of the GCC Runtime Library Exception along with this program;     --
19-- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
20-- <http://www.gnu.org/licenses/>.                                          --
21--                                                                          --
22------------------------------------------------------------------------------
23
24--  Regions -- Representing a pixel-aligned area
25--  <description>
26--  Bindings to the Cairo 2D graphics library.
27--  Regions are a simple graphical data type representing an area of integer-
28--  aligned rectangles. Thay are often used on raster surfaces to track areas
29--  of interest, such as change or clip areas.
30--  </description>
31--
32--  <c_version>1.10</c_version>
33--  <group>Cairo</group>
34
35package Cairo.Region is
36
37   type Cairo_Region is private;
38   --  A Cairo_Region represents a set of integer-aligned rectangles.
39   --
40   --  It allows set-theoretical operations like Union and Intersect to be
41   --  performed on them.
42   --
43   --  Memory management of Cairo_Region is done with Reference and
44   --  Destroy.
45   --
46   --  Since: 1.10
47
48   Null_Region : constant Cairo_Region;
49
50   type Cairo_Rectangle_Int is record
51      X, Y, Width, Height : aliased Gint;
52   end record;
53
54   type Cairo_Region_Overlap is
55     (Cairo_Region_Overlap_In,    --  Completely inside region
56      Cairo_Region_Overlap_Out,   --  Completely outside region
57      Cairo_Region_Overlap_Part   --  Partly inside region
58     );
59   --  Used as the return value for Contains_Rectangle.
60   pragma Convention (C, Cairo_Region_Overlap);
61
62   function Create return Cairo_Region;
63   --  Allocates a new empty region object.
64   --
65   --  Returns: A newly allocated Cairo_Region. Free with Destroy. This
66   --  function always returns a valid Cairo_Region; if memory cannot be
67   --  allocated, then a special error object is returned where all operations
68   --  on the object do nothing. You can check for this with Status.
69
70   function Create_Rectangle
71     (Rectangle : access Cairo_Rectangle_Int) return Cairo_Region;
72   --  Allocates a new region object containing Rectangle.
73   --
74   --  Returns: A newly allocated Cairo_Region. Free with Destroy. This
75   --  function always returns a valid Cairo_Region; if memory cannot be
76   --  allocated, then a special error object is returned where all operations
77   --  on the object do nothing. You can check for this with Status.
78
79   function Copy (Original : Cairo_Region) return Cairo_Region;
80   --  Allocates a new Cairo_Region object copying the area from Original.
81   --
82   --  Returns: A newly allocated Cairo_Region. Free with Destroy. This
83   --  function always returns a valid Cairo_Region; if memory cannot be
84   --  allocated, then a special error object is returned where all operations
85   --  on the object do nothing. You can check for this with Status.
86
87   function Reference (Region : Cairo_Region) return Cairo_Region;
88   --  Increases the reference count on Region by one. This prefents Region
89   --  from being destroyed until a matching call to Destroy is made.
90
91   procedure Destroy (Region : Cairo_Region);
92   --  Destroys a Cairo_Region object created with Create, Copy or
93   --  Create_Rectangle.
94
95   function "=" (A, B : Cairo_Region) return Boolean;
96   --  Compares whether A is equivalent to B. Null_Region as an argument is
97   --  equal to itself, but not to any non-Null_Region region.
98
99   function Status (Region : Cairo_Region) return Cairo_Status;
100   --  Checks whether an error has occured for this region object.
101   --
102   --  Returns: Cairo_Status_Success or Cairo_Status_No_Memory
103
104   procedure Get_Extents
105     (Region  : Cairo_Region;
106      Extents : out Cairo_Rectangle_Int);
107   --  Gets the bounding rectangle of Region as a Cairo_Rectangle_Int
108
109   function Num_Rectangles (Region : Cairo_Region) return Gint;
110   --  Returns the number of rectangle contained in Region
111
112   procedure Get_Rectangle
113     (Region    : Cairo_Region;
114      Nth       : Gint;
115      Rectangle : out Cairo_Rectangle_Int);
116   --  Stores the Nth rectangle from the region in Rectangle.
117
118   function Is_Empty (Region : Cairo_Region) return Boolean;
119   --  Checks whether Region is empty.
120
121   function Contains_Rectangle
122     (Region    : Cairo_Region;
123      Rectangle : access Cairo_Rectangle_Int) return Cairo_Region_Overlap;
124   --  Checks whether Rectangle is inside, outside or partially contained in
125   --  Region
126
127   function Contains_Point
128     (Region : Cairo_Region;
129      X      : Gint;
130      Y      : Gint) return Boolean;
131   --  Checks whether (X,Y) is contained in Region.
132
133   procedure Translate
134     (Region : Cairo_Region;
135      dX     : Gint;
136      dY     : Gint);
137   --  Translates Region by (dX,dY).
138
139   function Subtract
140     (Dst   : Cairo_Region;
141      Other : Cairo_Region) return Cairo_Status;
142   --  Subtracts Other from Dst and places the result in Dst.
143   --
144   --  Returns: Cairo_Status_Success or Cairo_Status_No_Memory.
145
146   function Subtract_Rectangle
147     (Dst       : Cairo_Region;
148      Rectangle : access Cairo_Rectangle_Int) return Cairo_Status;
149   --  Subtracts Rectangle from Dst and places the result in Dst.
150   --
151   --  Returns: Cairo_Status_Success or Cairo_Status_No_Memory.
152
153   function Intersect
154     (Dst   : Cairo_Region;
155      Other : Cairo_Region) return Cairo_Status;
156   --  Computes the intersection of Dst with Other and places the result in Dst
157   --
158   --  Returns: Cairo_Status_Success or Cairo_Status_No_Memory.
159
160   function Intersect_Rectangle
161     (Dst       : Cairo_Region;
162      Rectangle : access Cairo_Rectangle_Int) return Cairo_Status;
163   --  Computes the intersection of Dst with Rectangle and places the result in
164   --  Dst.
165   --
166   --  Returns: Cairo_Status_Success or Cairo_Status_No_Memory.
167
168   function Union
169     (Dst   : Cairo_Region;
170      Other : Cairo_Region) return Cairo_Status;
171   --  Computes the union of Dst with Other and places the result in Dst.
172   --
173   --  Returns: Cairo_Status_Success or Cairo_Status_No_Memory.
174
175   function Union_Rectangle
176     (Dst       : Cairo_Region;
177      Rectangle : access Cairo_Rectangle_Int) return Cairo_Status;
178   --  Computes the union of Dst with Rectangle and places the result in Dst.
179   --
180   --  Returns: Cairo_Status_Success or Cairo_Status_No_Memory.
181
182   function Do_Xor
183     (Dst   : Cairo_Region;
184      Other : Cairo_Region) return Cairo_Status;
185   --  Computes the exclusive difference of Dst with Other and places the
186   --  result in Dst.
187   --
188   --  Returns: Cairo_Status_Success or Cairo_Status_No_Memory.
189
190   function Xor_Rectangle
191     (Dst       : Cairo_Region;
192      Rectangle : access Cairo_Rectangle_Int) return Cairo_Status;
193   --  Computes the exclusive difference of Dst with Rectangle and places the
194   --  result in Dst.
195   --
196   --  Returns: Cairo_Status_Success or Cairo_Status_No_Memory.
197
198private
199
200   pragma Convention (C, Cairo_Rectangle_Int);
201
202   type Cairo_Region is new System.Address;
203   Null_Region : constant Cairo_Region := Cairo_Region (System.Null_Address);
204
205   pragma Import (C, Create, "cairo_region_create");
206   pragma Import (C, Create_Rectangle, "cairo_region_create_rectangle");
207   pragma Import (C, Copy, "cairo_region_copy");
208   pragma Import (C, Reference, "cairo_region_reference");
209   pragma Import (C, Destroy, "cairo_region_destroy");
210   pragma Import (C, Status, "cairo_region_status");
211   pragma Import (C, Get_Extents, "cairo_region_get_extents");
212   pragma Import (C, Num_Rectangles, "cairo_region_num_rectangles");
213   pragma Import (C, Get_Rectangle, "cairo_region_get_rectangle");
214   pragma Import (C, Contains_Rectangle, "cairo_region_contains_rectangle");
215   pragma Import (C, Translate, "cairo_region_translate");
216   pragma Import (C, Subtract, "cairo_region_subtract");
217   pragma Import (C, Subtract_Rectangle, "cairo_region_subtract_rectangle");
218   pragma Import (C, Intersect, "cairo_region_intersect");
219   pragma Import (C, Intersect_Rectangle, "cairo_region_intersect_rectangle");
220   pragma Import (C, Union, "cairo_region_union");
221   pragma Import (C, Union_Rectangle, "cairo_region_union_rectangle");
222   pragma Import (C, Do_Xor, "cairo_region_xor");
223   pragma Import (C, Xor_Rectangle, "cairo_region_xor_rectangle");
224   pragma Inline ("=");
225   pragma Inline (Is_Empty);
226
227end Cairo.Region;
228