## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

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

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

3.     --                                                                   --

4.     --   Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet   --

5.     --                Copyright (C) 2000-2002 ACT-Europe                 --

6.     --                                                                   --

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

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

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

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

11.     --                                                                   --

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

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

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

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

16.     --                                                                   --

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

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

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

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

21.     --                                                                   --

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

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

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

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

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

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

28.     -----------------------------------------------------------------------

30.     --  <description>

31.     --

32.     --  A graphic context is a structure that describes all the attributes

33.     --  used by the drawing functions in Gdk.

34.     --  The colors, line styles, Fill styles and so on are defined through

35.     --  this structure.

36.     --

37.     --  On X11 systems, this structure is stored directly on the XServer,

38.     --  which speeds up the transfer of the drawing attributes a lot. Instead

39.     --  of transferring all of them every time you call one of the drawing

40.     --  functions, you simply specify which GC you want to use.

41.     --

42.     --  Thus, it is recommended to create as many GCs as you need, instead

43.     --  of creating a single one that is modified every time you need to

44.     --  modify one of the attributes.

45.     --

46.     --  On Unix machines, you should have a look at the external utility 'xgc'

47.     --  which demonstrates all the basic settings of the graphic contexts.

48.     --

49.     --  </description>

50.     --  <c_version>1.3.6</c_version>

51.     --  <group>Gdk, the low-level API</group>

52.     --  <testgtk>create_gc.adb</testgtk>

53.     --  <see>Gtk.GC</see>

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

56.     with Gdk.ColorTo API docTo specTo body;

57.     with Gdk.FontTo API docTo specTo body;

58.     with Gdk.RectangleTo API docTo specTo body;

59.     with Gdk.RegionTo API docTo specTo body;

61.     package Gdk.GCTo API docTo specTo body is

63.        subtype Gdk_GC is Gdk.Gdk_GCTo API docTo spec;

64.        --  A graphic context that contain all the information to draw graphics

65.        --  on the screen.

66.        --  Creating these GC is more efficient than passing a lot of parameters

67.        --  to each of the drawing functions, since these GC are stored on the

68.        --  server side and do not need to be pass through the network.

70.        type Gdk_GC_Values is new Gdk.C_ProxyTo API docTo spec;

71.        --  A structure used on the client side to store the same information

72.        --  as the GC. Creating a GC from this structure is more efficient than

73.        --  calling a lot of functions to modify the GC directly, since there is

74.        --  a single call to the server.

76.        type Gdk_Cap_Style is (Cap_Not_Last, Cap_Butt, Cap_Round, Cap_Projecting);

77.        pragma Convention (C, Gdk_Cap_StyleTo API docTo spec);

79.        type Gdk_Fill is (Solid, Tiled, Stippled, Opaque_Stippled);

80.        pragma Convention (C, Gdk_FillTo API docTo spec);

82.        type Gdk_Function is

83.          (Copy,

84.           Invert,

85.           Gdk_Xor,

86.           Clear,

87.           Gdk_And,

88.           And_Reverse,

89.           And_Invert,

90.           Noop,

91.           Gdk_Or,

92.           Equiv,

93.           Or_Reverse,

94.           Copy_Invert,

95.           Or_Invert,

96.           Nand,

97.           Set);

98.        pragma Convention (C, Gdk_FunctionTo API docTo spec);

100.        type Gdk_Join_Style is (Join_Miter, Join_Round, Join_Bevel);

101.        pragma Convention (C, Gdk_Join_StyleTo API docTo spec);

103.        type Gdk_Line_Style is (Line_Solid, Line_On_Off_Dash, Line_Double_Dash);

104.        pragma Convention (C, Gdk_Line_StyleTo API docTo spec);

106.        type Gdk_Subwindow_Mode is (Clip_By_Children, Include_Inferiors);

107.        pragma Convention (C, Gdk_Subwindow_ModeTo API docTo spec);

109.        type Gdk_GC_Values_Mask is mod 2 ** 32;

110.        GC_Foreground    : constant Gdk_GC_Values_MaskTo API docTo spec := 2 ** 0;

111.        GC_Background    : constant Gdk_GC_Values_MaskTo API docTo spec := 2 ** 1;

112.        GC_Font          : constant Gdk_GC_Values_MaskTo API docTo spec := 2 ** 2;

113.        GC_Function      : constant Gdk_GC_Values_MaskTo API docTo spec := 2 ** 3;

114.        GC_Fill          : constant Gdk_GC_Values_MaskTo API docTo spec := 2 ** 4;

115.        GC_Tile          : constant Gdk_GC_Values_MaskTo API docTo spec := 2 ** 5;

116.        GC_Stipple       : constant Gdk_GC_Values_MaskTo API docTo spec := 2 ** 6;

117.        GC_Clip_Mask     : constant Gdk_GC_Values_MaskTo API docTo spec := 2 ** 7;

118.        GC_Subwindow     : constant Gdk_GC_Values_MaskTo API docTo spec := 2 ** 8;

119.        GC_Ts_X_Origin   : constant Gdk_GC_Values_MaskTo API docTo spec := 2 ** 9;

120.        GC_Tx_Y_Origin   : constant Gdk_GC_Values_MaskTo API docTo spec := 2 ** 10;

121.        GC_Clip_X_Origin : constant Gdk_GC_Values_MaskTo API docTo spec := 2 ** 11;

122.        GC_Clip_Y_Origin : constant Gdk_GC_Values_MaskTo API docTo spec := 2 ** 12;

123.        GC_Exposures     : constant Gdk_GC_Values_MaskTo API docTo spec := 2 ** 13;

124.        GC_Line_Width    : constant Gdk_GC_Values_MaskTo API docTo spec := 2 ** 14;

125.        GC_Line_Style    : constant Gdk_GC_Values_MaskTo API docTo spec := 2 ** 15;

126.        GC_Cap_Style     : constant Gdk_GC_Values_MaskTo API docTo spec := 2 ** 16;

127.        GC_Join_Style    : constant Gdk_GC_Values_MaskTo API docTo spec := 2 ** 17;

129.        Null_GC : constant Gdk_GCTo API docTo spec := null;

130.        Null_GC_Values : constant Gdk_GC_ValuesTo API docTo spec := null;

132.        ------------

133.        -- Gdk_GC --

134.        ------------

136.        procedure Gdk_NewTo API docTo body

137.          (GC       : out Gdk_GCTo API docTo spec;

138.           Drawable : Gdk.Gdk_DrawableTo API docTo spec);

139.        --  Create a new graphic context.

140.        --  The window must have been realized first (so that it is associated

141.        --  with some resources on the Xserver).

142.        --  The GC can then be used for any window that has the same root window,

143.        --  and same color depth as Window.

144.        --  See the manual page for XCreateGC on Unix systems for more information.

146.        procedure Gdk_NewTo API docTo body

147.          (GC          : out Gdk_GCTo API docTo spec;

148.           Drawable    : Gdk.Gdk_DrawableTo API docTo spec;

149.           Values      : Gdk_GC_ValuesTo API docTo spec;

150.           Values_Mask : Gdk_GC_Values_MaskTo API docTo spec);

151.        --  Create a new graphic context.

152.        --  It is directly created with the values set in Values, and whose

153.        --  associated field has been set in Values_Mask.

154.        --  This is faster than calling the simple Gdk_New function and each of

155.        --  other functions in this package, since each of them requires a call

156.        --  to the server.

158.        function Get_TypeTo API docTo body return Glib.GTypeTo API docTo spec;

159.        --  Return the internal value associated with Gdk_GC.

161.        procedure DestroyTo API docTo body (GC : Gdk_GCTo API docTo spec);

162.        --  Free the memory allocated on the server for the graphic context.

163.        --  Graphic contexts are never freed automatically by GtkAda, this is

164.        --  the user responsibility to do so.

165.        --  This procedure is deprecated. Use Unref instead.

167.        procedure RefTo API docTo body (GC : Gdk_GCTo API docTo spec);

168.        --  Increment the reference counting for the graphic context.

170.        procedure UnrefTo API docTo body (GC : Gdk_GCTo API docTo spec);

171.        --  Decrement the reference counting for the graphic context.

172.        --  When this reaches 0, the graphic context is destroyed.

174.        procedure Get_ValuesTo API docTo body (GC : Gdk_GCTo API docTo spec; Values : Gdk_GC_ValuesTo API docTo spec);

175.        --  Get the values set in the GC.

176.        --  This copies the values from the server to client, allowing faster

177.        --  modifications. Values can then be copied back to the server by

178.        --  creating a new graphic context with the function Gdk_New above.

179.        --  Values should have been allocated first with a call to Gdk_New.

181.        procedure Set_ValuesTo API docTo body

182.          (GC     : Gdk_GCTo API docTo spec;

183.           Values : Gdk_GC_ValuesTo API docTo spec;

184.           Mask   : Gdk_GC_Values_MaskTo API docTo spec);

185.        --  Set the values in the GC.

186.        --  Mask indicates which values should be taken from Values and set in GC.

188.        procedure Set_ForegroundTo API docTo body (GC : Gdk_GCTo API docTo spec; ColorTo API docTo body : Gdk.Color.Gdk_ColorTo API docTo specTo body);

189.        --  Set the foreground color for the graphic context.

190.        --  This color is the one that is used by most drawing functions.

192.        procedure Set_BackgroundTo API docTo body (GC : Gdk_GCTo API docTo spec; ColorTo API docTo body : Gdk.Color.Gdk_ColorTo API docTo specTo body);

193.        --  Set the background color for the graphic context.

195.        procedure Set_FontTo API docTo body (GC : Gdk_GCTo API docTo spec; Font : Gdk.Font.Gdk_FontTo API docTo spec);

196.        --  Set the font used by the graphic context.

197.        --  This font is used by the function Gdk.Drawable.Draw_Text.

199.        procedure Set_FunctionTo API docTo body (GC : Gdk_GCTo API docTo spec; FuncTo API docTo body : Gdk_FunctionTo API docTo spec);

200.        --  Set the function in the graphic context.

201.        --  This function specifies how the points are put on the screen, ie

202.        --  if GtkAda how GtkAda should mix the point already on the screen

203.        --  and the new point being put.

204.        --  Note that setting the function to Gdk_Xor is not the right way

205.        --  to do animation. You should instead save the background pixmap,

206.        --  put the image, and then restore the background.

207.        --

208.        --  In general, there are three basic steps to drawing: reading the source

209.        --  pixels, reading the destination pixels, and writing the destination

210.        --  pixels.  Some functions only perform the third step (Set and Clear),

211.        --  some do not need the middle step (Copy), whereas most require the three

212.        --  steps, and thus can be much slower.

214.        procedure Set_FillTo API docTo body (GC : Gdk_GCTo API docTo spec; FillTo API docTo body : Gdk_FillTo API docTo spec);

215.        --  Set the pattern used for filling the polygons.

217.        procedure Set_TileTo API docTo body (GC : Gdk_GCTo API docTo spec; Tile : Gdk.Gdk_PixmapTo API docTo spec);

219.        procedure Set_StippleTo API docTo body (GC : Gdk_GCTo API docTo spec; Stipple : Gdk.Gdk_PixmapTo API docTo spec);

221.        procedure Set_Ts_OriginTo API docTo body (GC : Gdk_GCTo API docTo spec; X, Y : GintTo API docTo spec);

222.        --  Set the Tile and Stipple origin in the graphic context.

224.        procedure Set_Clip_OriginTo API docTo body (GC : Gdk_GCTo API docTo spec; X, Y : GintTo API docTo spec);

225.        --  Set the origin of the clip mask.

226.        --  See the functions Set_Clip_Rectangle, Set_Clip_Region and

227.        --  Gdk.Bitmap.Set_Clip_Mask for more explanation.

229.        procedure Set_Clip_MaskTo API docTo body (GC : Gdk.GC.Gdk_GCTo API docTo spec; Mask : Gdk.Gdk_BitmapTo API docTo spec);

230.        --  If Mask is set to Null_Bitmap, then no clip_mask is used for drawing.

231.        --  Points will be drawn through this GC only where the bits are set to 1

232.        --  in the mask. See also the function Set_Clip_Origin for

233.        --  how to move the mask inside the GC.

235.        procedure Set_Clip_RectangleTo API docTo body

236.          (GC : Gdk_GCTo API docTo spec; Rectangle : Gdk.Rectangle.Gdk_RectangleTo API docTo spec);

237.        procedure Set_Clip_RectangleTo API docTo body

238.          (GC : Gdk_GCTo API docTo spec; Rectangle : Gdk.Rectangle.Gdk_Rectangle_AccessTo API docTo spec := null);

239.        --  Set the clip rectangle.

240.        --  Only the points that are drawn inside this rectangle will be displayed

241.        --  on the screen. The clip origin is modified automatically.

242.        --  See Set_Clip_Mask to delete the current clip mask.

244.        procedure Set_Clip_RegionTo API docTo body (GC : Gdk_GCTo API docTo spec; Region : Gdk.Region.Gdk_RegionTo API docTo spec);

245.        --  Define a clip region on the screen.

246.        --  This is just like Set_Clip_Rectangle, except that a region is a more

247.        --  complex region, that can be the intersection or union of multiple

248.        --  rectangles. Note that the Clip_Origin can have an influence on this

249.        --  function.

251.        procedure Set_SubwindowTo API docTo body (GC : Gdk_GCTo API docTo spec; ModeTo API docTo body : Gdk_Subwindow_ModeTo API docTo spec);

252.        --  Set the subwindow mode for the graphic context.

253.        --  This specifies whether the drawing routines should be clipped to

254.        --  the specific window they are drawn into, or if they should extend

255.        --  to subwindows as well.

257.        procedure Set_ExposuresTo API docTo body (GC : Gdk_GCTo API docTo spec; Exposures : Boolean);

258.        --  Exposures indicates whether you want "expose" and "noexpose" events to

259.        --  be reported when calling Copy_Area and Copy_Plane with this GC.

260.        --  You should disable this if you don't need the event and want to optimize

261.        --  your application.

262.        --  If Exposures is True, then any call to Copy_Area or Draw_Pixmap will

263.        --  generate an expose event. Otherwise, these will generate a no_expose

264.        --  event.

266.        procedure Set_Line_AttributesTo API docTo body

267.          (GC         : Gdk_GCTo API docTo spec;

268.           Line_Width : GintTo API docTo spec;

269.           Line_StyleTo API docTo body : Gdk_Line_StyleTo API docTo spec;

270.           Cap_StyleTo API docTo body  : Gdk_Cap_StyleTo API docTo spec;

271.           Join_StyleTo API docTo body : Gdk_Join_StyleTo API docTo spec);

272.        --  Set the line attributes for this GC.

273.        --  Line_Width is the width of the line. If its value is 0, the line is as

274.        --  thin as possible, possibly even more so than if the width is 1. It is

275.        --  also faster to draw a line with width 0 than any other line width.

276.        --

277.        --  Line_Style specifies whether the line should be solid or dashed.

278.        --  With Line_On_Off_Dash, the colors are alternatively the foreground

279.        --  color, and blank. With Line_Double_Dash, the colors are

280.        --  alternatively the foreground and background colors.

281.        --

282.        --  Cap_Style specifies how the line should end, either flat or rounded.

283.        --

284.        --  Join_Style specifies how two consecutive lines drawn by Draw_Lines are

285.        --  connected.

287.        procedure Set_DashesTo API docTo body

288.          (Gc          : Gdk_GCTo API docTo spec;

289.           Dash_Offset : GintTo API docTo spec;

290.           Dash_List   : Guchar_ArrayTo API docTo spec);

291.        --  Specify the dash pattern when the line's style is anything but solid.

292.        --  The values in the array alternatively give the length (in pixels) of

293.        --  the plain dash, the empty dash, the second plain dash, ... None of

294.        --  these values can be 0. If there is an odd number of items in Dash_List,

295.        --  this is equivalent to giving the array concatenated with itself.

296.        --  Dash_Offset specifies the phase of the pattern to start with.

298.        procedure CopyTo API docTo body (Dst_GC : Gdk_GCTo API docTo spec; Src_GC : Gdk_GCTo API docTo spec);

299.        --  Copy a Src_GC to Dst_GC.

301.        procedure Set_ColormapTo API docTo body (Gc : Gdk_GCTo API docTo spec; Colormap : Gdk.Gdk_ColormapTo API docTo spec);

303.        function Get_ColormapTo API docTo body (Gc : Gdk_GCTo API docTo spec) return Gdk.Gdk_ColormapTo API docTo spec;

305.        procedure Set_Rgb_Fg_ColorTo API docTo body (Gc : Gdk_GCTo API docTo spec; Color : Gdk.Color.Gdk_ColorTo API docTo specTo body);

307.        procedure Set_Rgb_Bg_ColorTo API docTo body (Gc : Gdk_GCTo API docTo spec; Color : Gdk.Color.Gdk_ColorTo API docTo specTo body);

309.        ----------------------

310.        -- Gdk_Color_Values --

311.        ----------------------

313.        function Gdk_NewTo API docTo body return Gdk_GC_ValuesTo API docTo spec;

314.        --  Allocate a new Values structure on the client.

315.        --  Note that this function allocates a C structure, and thus needs to

316.        --  be freed with a call to Free below.

318.        procedure FreeTo API docTo body (Values : Gdk_GC_ValuesTo API docTo spec);

319.        --  Free the C structure associated with Values.

321.        procedure Set_ForegroundTo API docTo body

322.          (Values : Gdk_GC_ValuesTo API docTo spec; ColorTo API docTo body : Gdk.Color.Gdk_ColorTo API docTo specTo body);

323.        --  Same as Set_Foreground, but on the client side

325.        procedure Set_BackgroundTo API docTo body

326.          (Values : Gdk_GC_ValuesTo API docTo spec; ColorTo API docTo body : Gdk.Color.Gdk_ColorTo API docTo specTo body);

327.        --  Same as Set_Background, but on the client side

329.        procedure Set_FontTo API docTo body (Values : Gdk_GC_ValuesTo API docTo spec; Font : Gdk.Font.Gdk_FontTo API docTo spec);

330.        --  Same as Set_Font, but on the client side

332.        procedure Set_FunctionTo API docTo body (Values : Gdk_GC_ValuesTo API docTo spec; FuncTo API docTo body : Gdk_FunctionTo API docTo spec);

333.        --  Same as Set_Function, but on the client side

335.        procedure Set_FillTo API docTo body (Values : Gdk_GC_ValuesTo API docTo spec; FillTo API docTo body : Gdk_FillTo API docTo spec);

336.        --  Same as Set_Fill, but on the client side

338.        procedure Set_Ts_OriginTo API docTo body

339.          (Values : Gdk_GC_ValuesTo API docTo spec;

340.           X, Y   : GintTo API docTo spec);

341.        --  Same as Set_Ts_Origin, but on the client side

343.        procedure Set_Clip_OriginTo API docTo body

344.          (Values : Gdk_GC_ValuesTo API docTo spec;

345.           X, Y   : GintTo API docTo spec);

346.        --  Same as Set_Clip_Origin, but on the client side

348.        procedure Set_SubwindowTo API docTo body

349.          (Values : Gdk_GC_ValuesTo API docTo spec;

350.           ModeTo API docTo body   : Gdk_Subwindow_ModeTo API docTo spec);

351.        --  Same as Set_Subwindow, but on the client side

353.        procedure Set_ExposuresTo API docTo body (Values : Gdk_GC_ValuesTo API docTo spec; Exposures : Boolean);

354.        --  Same as Set_Exposures, but on the client side

356.        procedure Set_Line_AttributesTo API docTo body

357.          (Values     : Gdk_GC_ValuesTo API docTo spec;

358.           Line_Width : GintTo API docTo spec;

359.           Line_StyleTo API docTo body : Gdk_Line_StyleTo API docTo spec;

360.           Cap_StyleTo API docTo body  : Gdk_Cap_StyleTo API docTo spec;

361.           Join_StyleTo API docTo body : Gdk_Join_StyleTo API docTo spec);

362.        --  Same as Set_Line_Attributes, but on the client side

364.     private

365.        pragma Import (C, Get_TypeTo API docTo spec, "gdk_gc_get_type");

366.        pragma Import (C, Copy, "gdk_gc_copy");

367.        pragma Import (C, DestroyTo API docTo spec, "gdk_gc_unref");

368.        pragma Import (C, FreeTo API docTo spec, "ada_gdk_gc_free_values");

369.        pragma Import (C, Get_ValuesTo API docTo spec, "gdk_gc_get_values");

370.        pragma Import (C, Set_ValuesTo API docTo spec, "gdk_gc_set_values");

371.        pragma Import (C, RefTo API docTo spec, "gdk_gc_ref");

372.        pragma Import (C, UnrefTo API docTo spec, "gdk_gc_unref");

373.        pragma Import (C, Set_Clip_RectangleTo API docTo spec, "gdk_gc_set_clip_rectangle");

374.        pragma Import (C, Set_Clip_RegionTo API docTo spec, "gdk_gc_set_clip_region");

375.        pragma Import (C, Set_StippleTo API docTo spec, "gdk_gc_set_stipple");

376.        pragma Import (C, Set_TileTo API docTo spec, "gdk_gc_set_tile");

377.        pragma Import (C, Set_Clip_MaskTo API docTo spec, "gdk_gc_set_clip_mask");

378.        pragma Import (C, Set_ColormapTo API docTo spec, "gdk_gc_set_colormap");

379.        pragma Import (C, Get_ColormapTo API docTo spec, "gdk_gc_get_colormap");

380.        pragma Import (C, Set_Rgb_Fg_ColorTo API docTo spec, "gdk_gc_set_rgb_fg_color");

381.        pragma Import (C, Set_Rgb_Bg_ColorTo API docTo spec, "gdk_gc_set_rgb_bg_color");

382.     end Gdk.GCTo API docTo specTo body;