## 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.     --  A Cairo_Surface is the abstract type representing all different drawing

31.     --  targets that cairo can render to. The actual drawings are performed using a

32.     --  Cairo_Context.

33.     --  </description>

34.     --

35.     --  <c_version>1.8.8</c_version>

36.     --  <group>Cairo</group>

38.     with System;

40.     package Cairo.SurfaceTo API docTo spec is

42.        --------------------------

43.        -- Surface manipulation --

44.        --------------------------

46.        type Cairo_Surface_Type is

47.          (Cairo_Surface_Type_Image,

48.           Cairo_Surface_Type_Pdf,

49.           Cairo_Surface_Type_Ps,

50.           Cairo_Surface_Type_Xlib,

51.           Cairo_Surface_Type_Xcb,

52.           Cairo_Surface_Type_Glitz,

53.           Cairo_Surface_Type_Quartz,

54.           Cairo_Surface_Type_Win32,

55.           Cairo_Surface_Type_Beos,

56.           Cairo_Surface_Type_Directfb,

57.           Cairo_Surface_Type_Svg,

58.           Cairo_Surface_Type_Os2,

59.           Cairo_Surface_Type_Win32_Printing,

60.           Cairo_Surface_Type_Quartz_Image);

61.        pragma Convention (C, Cairo_Surface_TypeTo API docTo spec);

62.        --  Cairo_Surface_Type is used to describe the type of a given

63.        --  surface. The surface types are also known as "backends" or "surface

64.        --  backends" within cairo.

65.        --

66.        --  The type of a surface is determined by the function used to create

67.        --  it, which will generally be of the form

68.        --  Cairo.<type>_Surface_Create,

69.        --  (though see Cairo.Surface.Create_Similar as well).

70.        --

71.        --  The surface type can be queried with Cairo.Surface.Get_Type

72.        --

73.        --  The various Cairo_surface functions can be used with surfaces of

74.        --  any type, but some backends also provide type-specific functions

75.        --  that must only be called with a surface of the appropriate

76.        --  type. These functions have names that begin with

77.        --  Cairo.<type>_Surface.* such as

78.        --  Cairo.Image_Surface.Get_Width.

79.        --

80.        --  The behavior of calling a type-specific function with a surface of

81.        --  the wrong type is undefined.

82.        --

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

84.        --

85.        --  Since: 1.2

87.        function Create_SimilarTo API docTo body

88.          (Other   : Cairo_SurfaceTo API docTo spec;

89.           Content : Cairo_ContentTo API docTo spec;

90.           Width   : GintTo API docTo spec;

91.           Height  : GintTo API docTo spec)

92.           return    Cairo_SurfaceTo API docTo spec;

93.        --  Other: an existing surface used to select the backend of the new surface

94.        --  Content: the Content for the new surface

95.        --  Width: Width of the new surface, (in device-space units)

96.        --  Height: Height of the new surface (in device-space units)

97.        --

98.        --  Create a new surface that is as compatible as possible with an

99.        --  existing surface. For example the new surface will have the same

100.        --  fallback resolution and font options as other. Generally, the new

101.        --  surface will also use the same backend as other, unless that is

102.        --  not possible for some reason. The type of the returned surface may

103.        --  be examined with Cairo.Surface.Get_Type.

104.        --

105.        --  Initially the surface contents are all 0 (transparent if contents

106.        --  have transparency, black otherwise.)

107.        --

108.        --  Return value: a pointer to the newly allocated surface. The caller

109.        --  owns the surface and should call Cairo.Surface.Destroy when done

110.        --  with it.

111.        --

112.        --  This function always returns a valid pointer, but it will return a

113.        --  pointer to a "nil" surface if other is already in an error state

114.        --  or any other error occurs.

116.        function ReferenceTo API docTo body (Surface : Cairo_SurfaceTo API docTo spec) return Cairo_SurfaceTo API docTo spec;

117.        --  Surface: a Cairo_Surface

118.        --

119.        --  Increases the reference count on surface by one. This prevents

120.        --  surface from being destroyed until a matching call to

121.        --  Cairo.Surface.Destroy is made.

122.        --

123.        --  The number of references to a Cairo_Surface can be get using

124.        --  Cairo.Surface.Get_Reference_Count.

125.        --

126.        --  Return value: the referenced Cairo_Surface.

128.        procedure FinishTo API docTo body (Surface : Cairo_SurfaceTo API docTo spec);

129.        --  Surface: the Cairo_Surface to finish

130.        --

131.        --  This function finishes the surface and drops all references to

132.        --  external resources.  For example, for the Xlib backend it means

133.        --  that cairo will no longer access the drawable, which can be freed.

134.        --  After calling Cairo.Surface.Finish the only valid operations on a

135.        --  surface are getting and setting user, referencing and

136.        --  destroying, and flushing and finishing it.

137.        --  Further drawing to the surface will not affect the

138.        --  surface but will instead trigger a Cairo_Status_Surface_Finished

139.        --  error.

140.        --

141.        --  When the last call to Cairo.Surface.Destroy decreases the

142.        --  reference count to zero, cairo will call Cairo.Surface.Finish if

143.        --  it hasn't been called already, before freeing the resources

144.        --  associated with the surface.

146.        procedure DestroyTo API docTo body (Surface : Cairo_SurfaceTo API docTo spec);

147.        --  Surface: a Cairo_Surface

148.        --

149.        --  Decreases the reference count on surface by one. If the result is

150.        --  zero, then surface and all associated resources are freed.  See

151.        --  Cairo.Surface.Reference.

153.        function Get_Reference_CountTo API docTo body (Surface : Cairo_SurfaceTo API docTo spec) return GuintTo API docTo spec;

154.        --  Surface: a Cairo_Surface

155.        --

156.        --  Returns the current reference count of surface.

157.        --

158.        --  Return value: the current reference count of surface.  If the

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

160.        --

161.        --  Since: 1.4

163.        function StatusTo API docTo body (Surface : Cairo_SurfaceTo API docTo spec) return Cairo_StatusTo API docTo spec;

164.        --  Surface: a Cairo_Surface

165.        --

166.        --  Checks whether an error has previously occurred for this

167.        --  surface.

168.        --

169.        --  Return value: Cairo_Status_Success, Cairo_Status_Null_Pointer,

170.        --     Cairo_Status_No_Memory, Cairo_Status_Read_Error,

171.        --     Cairo_Status_Invalid_Content, Cairo_Status_Invalid_Format, or

172.        --     Cairo_Status_Invalid_Visual.

174.        function Get_TypeTo API docTo body (Surface : Cairo_SurfaceTo API docTo spec) return Cairo_Surface_TypeTo API docTo spec;

175.        --  Surface: a Cairo_Surface

176.        --

177.        --  This function returns the type of the backend used to create

178.        --  a surface. See Cairo_Surface_Type for available types.

179.        --

180.        --  Return value: The type of surface.

181.        --

182.        --  Since: 1.2

184.        function Get_ContentTo API docTo body (Surface : Cairo_SurfaceTo API docTo spec) return Cairo_ContentTo API docTo spec;

185.        --  Surface: a Cairo_Surface

186.        --

187.        --  This function returns the content type of surface which indicates

188.        --  whether the surface contains color and/or alpha information. See

189.        --  Cairo_Content.

190.        --

191.        --  Return value: The content type of surface.

192.        --

193.        --  Since: 1.2

195.        function Get_User_DataTo API docTo body

196.          (Surface : Cairo_SurfaceTo API docTo spec;

197.           Key     : access Cairo_User_Data_KeyTo API docTo spec) return System.Address;

198.        --  Surface: a Cairo_Surface

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

200.        --  attached to

201.        --

202.        --  Return user data previously attached to surface using the specified

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

204.        --  function returns null.

205.        --

206.        --  Return value: the user data previously attached or null.

208.        function Set_User_DataTo API docTo body

209.          (Surface   : Cairo_SurfaceTo API docTo spec;

210.           Key       : access Cairo_User_Data_KeyTo API docTo spec;

211.           User_Data : System.Address;

212.           Destroy   : Cairo_Destroy_FuncTo API docTo spec) return Cairo_StatusTo API docTo spec;

213.        --  Surface: a Cairo_Surface

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

215.        --  User_Data: the user data to attach to the surface

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

217.        --  surface is destroyed or when new user data is attached using the

218.        --  same key.

219.        --

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

221.        --  call this function with the key that was used to set it and null

222.        --  for data.

223.        --

224.        --  Return value: Cairo_Status_Success or Cairo_Status_No_Memory if a

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

227.        procedure Get_Font_OptionsTo API docTo body

228.          (Surface : Cairo_SurfaceTo API docTo spec;

229.           Options : access Cairo_Font_OptionsTo API docTo spec);

230.        --  Surface: a Cairo_Surface

231.        --  Options: a Cairo_Font_Options object into which to store

232.        --    the retrieved options. All existing values are overwritten

233.        --

234.        --  Retrieves the default font rendering options for the surface.

235.        --  This allows display surfaces to report the correct subpixel order

236.        --  for rendering on them, print surfaces to disable hinting of

237.        --  metrics and so forth. The result can then be used with

238.        --  Cairo.Scaled_Font.Create.

240.        procedure FlushTo API docTo body (Surface : Cairo_SurfaceTo API docTo spec);

241.        --  Surface: a Cairo_Surface

242.        --

243.        --  Do any pending drawing for the surface and also restore any

244.        --  temporary modification's cairo has made to the surface's

245.        --  state. This function must be called before switching from

246.        --  drawing on the surface with cairo to drawing on it directly

247.        --  with native APIs. If the surface doesn't support direct access,

248.        --  then this function does nothing.

250.        procedure Mark_DirtyTo API docTo body (Surface : Cairo_SurfaceTo API docTo spec);

251.        --  Surface: a Cairo_Surface

252.        --

253.        --  Tells cairo that drawing has been done to surface using means other

254.        --  than cairo, and that cairo should reread any cached areas. Note

255.        --  that you must call Cairo.Surface.Flush before doing such drawing.

257.        procedure Mark_Dirty_RectangleTo API docTo body

258.          (Surface : Cairo_SurfaceTo API docTo spec;

259.           X       : GintTo API docTo spec;

260.           Y       : GintTo API docTo spec;

261.           Width   : GintTo API docTo spec;

262.           Height  : GintTo API docTo spec);

263.        --  Surface: a Cairo_Surface

264.        --  X: X coordinate of dirty rectangle

265.        --  Y: Y coordinate of dirtY rectangle

266.        --  Width: Width of dirty rectangle

267.        --  Height: Height of dirty rectangle

268.        --

269.        --  Like Cairo.Surface.Mark_Dirty, but drawing has been done only to

270.        --  the specified rectangle, so that cairo can retain cached contents

271.        --  for other parts of the surface.

272.        --

273.        --  Any cached clip set on the surface will be reset by this function,

274.        --  to make sure that future cairo calls have the clip set that they

275.        --  expect.

277.        procedure Set_Device_OffsetTo API docTo body

278.          (Surface  : Cairo_SurfaceTo API docTo spec;

279.           X_Offset : GdoubleTo API docTo spec;

280.           Y_Offset : GdoubleTo API docTo spec);

281.        --  Surface: a Cairo_Surface

282.        --  X_Offset: the offset in the X direction, in device units

283.        --  Y_Offset: the offset in the Y direction, in device units

284.        --

285.        --  Sets an offset that is added to the device coordinates determined

286.        --  by the CTM when drawing to surface. One use case for this function

287.        --  is when we want to create a Cairo_Surface that redirects drawing

288.        --  for a portion of an onscreen surface to an offscreen surface in a

289.        --  way that is completely invisible to the user of the cairo

290.        --  API. Setting a transformation via Cairo.Translate isn't

291.        --  sufficient to do this, since functions like

292.        --  Cairo.Device_To_User will expose the hidden offset.

293.        --

294.        --  Note that the offset affects drawing to the surface as well as

295.        --  using the surface in a source pattern.

297.        procedure Get_Device_OffsetTo API docTo body

298.          (Surface  : Cairo_SurfaceTo API docTo spec;

299.           X_Offset : access GdoubleTo API docTo spec;

300.           Y_Offset : access GdoubleTo API docTo spec);

301.        --  Surface: a Cairo_Surface

302.        --  X_Offset: the offset in the X direction, in device units

303.        --  Y_Offset: the offset in the Y direction, in device units

304.        --

305.        --  This function returns the previous device offset set by

306.        --  Cairo.Surface.Set_Device_Offset.

307.        --

308.        --  Since: 1.2

310.        procedure Set_Fallback_ResolutionTo API docTo body

311.          (Surface           : Cairo_SurfaceTo API docTo spec;

312.           X_Pixels_Per_Inch : GdoubleTo API docTo spec;

313.           Y_Pixels_Per_Inch : GdoubleTo API docTo spec);

314.        --  Surface: a Cairo_Surface

315.        --  X_Pixels_Per_Inch: horizontal setting for pixels per inch

316.        --  Y_Pixels_Per_Inch: vertical setting for pixels per inch

317.        --

318.        --  Set the horizontal and vertical resolution for image fallbacks.

319.        --

320.        --  When certain operations aren't supported natively by a backend,

321.        --  cairo will fallback by rendering operations to an image and then

322.        --  overlaying that image onto the output. For backends that are

323.        --  natively vector-oriented, this function can be used to set the

324.        --  resolution used for these image fallbacks, (larger values will

325.        --  result in more detailed images, but also larger file sizes).

326.        --

327.        --  Some examples of natively vector-oriented backends are the ps, pdf,

328.        --  and svg backends.

329.        --

330.        --  For backends that are natively raster-oriented, image fallbacks are

331.        --  still possible, but they are always performed at the native

332.        --  device resolution. So this function has no effect on those

333.        --  backends.

334.        --

335.        --  Note: The fallback resolution only takes effect at the time of

336.        --  completing a page (with Cairo.Show_Page or Cairo.Copy_Page) so

337.        --  there is currently no way to have more than one fallback resolution

338.        --  in effect on a single page.

339.        --

340.        --  The default fallback resoultion is 300 pixels per inch in both

341.        --  dimensions.

342.        --

343.        --  Since: 1.2

345.        procedure Get_Fallback_ResolutionTo API docTo body

346.          (Surface           : Cairo_SurfaceTo API docTo spec;

347.           X_Pixels_Per_Inch : access GdoubleTo API docTo spec;

348.           Y_Pixels_Per_Inch : access GdoubleTo API docTo spec);

349.        --  Surface: a Cairo_Surface

350.        --  X_Pixels_Per_Inch: horizontal pixels per inch

351.        --  Y_Pixels_Per_Inch: vertical pixels per inch

352.        --

353.        --  This function returns the previous fallback resolution set by

354.        --  Cairo.Surface.Set_Fallback_Resolution, or default fallback

355.        --  resolution if never set.

356.        --

357.        --  Since: 1.8

359.        procedure Copy_PageTo API docTo body (Surface : Cairo_SurfaceTo API docTo spec);

360.        --  Surface: a Cairo_Surface

361.        --

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

363.        --  but doesn't clear it, so that the contents of the current page will

364.        --  be retained for the next page.  Use Cairo.Surface.Show_Page if you

365.        --  want to get an empty page after the emission.

366.        --

367.        --  There is a convenience function for this that takes a Cairo_Context,

368.        --  namely Cairo.Copy_Page.

369.        --

370.        --  Since: 1.6

372.        procedure Show_PageTo API docTo body (Surface : Cairo_SurfaceTo API docTo spec);

373.        --  Surface: a Cairo_Surface

374.        --

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

376.        --  pages.  Use Cairo.Surface.Copy_Page if you don't want to clear the page.

377.        --

378.        --  There is a convenience function for this that takes a Cairo_Context,

379.        --  namely Cairo_Show_Page.

380.        --

381.        --  Since: 1.6

383.        function Has_Show_Text_GlyphsTo API docTo body

384.          (Surface : Cairo_SurfaceTo API docTo spec)

385.           return    Cairo_BoolTo API docTo spec;

386.        --  Surface: a Cairo_Surface

387.        --

388.        --  Returns whether the surface supports

389.        --  sophisticated Cairo_Show_Text_Glyphs operations.  That is,

390.        --  whether it actually uses the provided text and cluster data

391.        --  to a Cairo_Show_Text_Glyphs call.

392.        --

393.        --  Note: Even if this function returns FALSE, a

394.        --  Cairo_Show_Text_Glyphs operation targeted at surface will

395.        --  still succeed.  It just will

396.        --  act like a Cairo_Show_Glyphs operation.  Users can use this

397.        --  function to avoid computing UTF-8 text and cluster mapping if the

398.        --  target surface does not use it.

399.        --

400.        --  Return value: TRUE if surface supports

401.        --                Cairo_Show_Text_Glyphs, FALSE otherwise

402.        --

403.        --  Since: 1.8

405.     private

407.        pragma Import (C, Create_SimilarTo API docTo spec, "cairo_surface_create_similar");

408.        pragma Import (C, ReferenceTo API docTo spec, "cairo_surface_reference");

409.        pragma Import (C, FinishTo API docTo spec, "cairo_surface_finish");

410.        pragma Import (C, DestroyTo API docTo spec, "cairo_surface_destroy");

411.        pragma Import

412.          (C,

413.           Get_Reference_CountTo API docTo spec,

414.           "cairo_surface_get_reference_count");

415.        pragma Import (C, StatusTo API docTo spec, "cairo_surface_status");

416.        pragma Import (C, Get_TypeTo API docTo spec, "cairo_surface_get_type");

417.        pragma Import (C, Get_ContentTo API docTo spec, "cairo_surface_get_content");

418.        pragma Import (C, Get_User_DataTo API docTo spec, "cairo_surface_get_user_data");

419.        pragma Import (C, Set_User_DataTo API docTo spec, "cairo_surface_set_user_data");

420.        pragma Import (C, Get_Font_OptionsTo API docTo spec, "cairo_surface_get_font_options");

421.        pragma Import (C, FlushTo API docTo spec, "cairo_surface_flush");

422.        pragma Import (C, Mark_DirtyTo API docTo spec, "cairo_surface_mark_dirty");

423.        pragma Import

424.          (C,

425.           Mark_Dirty_RectangleTo API docTo spec,

426.           "cairo_surface_mark_dirty_rectangle");

427.        pragma Import (C, Set_Device_OffsetTo API docTo spec, "cairo_surface_set_device_offset");

428.        pragma Import (C, Get_Device_OffsetTo API docTo spec, "cairo_surface_get_device_offset");

429.        pragma Import

430.          (C,

431.           Set_Fallback_ResolutionTo API docTo spec,

432.           "cairo_surface_set_fallback_resolution");

433.        pragma Import

434.          (C,

435.           Get_Fallback_ResolutionTo API docTo spec,

436.           "cairo_surface_get_fallback_resolution");

437.        pragma Import (C, Copy_PageTo API docTo spec, "cairo_surface_copy_page");

438.        pragma Import (C, Show_PageTo API docTo spec, "cairo_surface_show_page");

439.        pragma Import

440.          (C,

441.           Has_Show_Text_GlyphsTo API docTo spec,

442.           "cairo_surface_has_show_text_glyphs");

444.     end Cairo.SurfaceTo API docTo spec;