## 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-2007 AdaCore                    --

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.     --  Base class for widgets that have children.

32.     --

33.     --  When writing your own container widgets, you need to fully handle the

34.     --  size_allocate event, by also resizing all the children (based on their size

35.     --  requisition). The size_allocate event will always be sent to the parent

36.     --  when a child calls Gtk.Widget.Queue_Resize.

37.     --  </description>

38.     --  <c_version>2.8.17</c_version>

39.     --  <group>Abstract base classes</group>

41.     with Gdk.EventTo API docTo specTo body;

42.     with Glib.PropertiesTo API docTo specTo body;

43.     with Glib.ValuesTo API docTo specTo body;

44.     with Gtk.AdjustmentTo API docTo specTo body;

45.     with Gtk.EnumsTo API docTo specTo body;

46.     with Gtk.WidgetTo API docTo specTo body;

48.     package Gtk.ContainerTo API docTo specTo body is

50.        type Gtk_Container_RecordTo API docTo body is new Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body with private;

51.        type Gtk_Container is access all Gtk_Container_RecordTo API docTo specTo body'Class;

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

54.        --  Return the internal value associated with a Gtk_Container.

56.        procedure Set_Border_WidthTo API docTo body

57.          (Container    : access Gtk_Container_RecordTo API docTo specTo body;

58.           Border_Width : GuintTo API docTo spec);

59.        function Get_Border_WidthTo API docTo body

60.          (Container    : access Gtk_Container_RecordTo API docTo specTo body) return GuintTo API docTo spec;

61.        --  Modify the size of the frame that surrounds the widget.

62.        --  The exact visual impact depends on the specific widget class.

64.        procedure AddTo API docTo body

65.          (Container : access Gtk_Container_RecordTo API docTo specTo body;

66.           Widget    : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class);

67.        --  Add a new child to the container.

68.        --  Note that some containers can have only one child. Nothing is done

69.        --  if there is already a child.

70.        --  This basically sends the "add" signal (see below)

72.        procedure RemoveTo API docTo body

73.          (Container : access Gtk_Container_RecordTo API docTo specTo body;

74.           Widget    : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class);

75.        --  Removes Widget from Container. Widget must be inside Container.

76.        --  Note that Container will own a reference to Widget, and that this

77.        --  may be the last reference held; so removing a widget from its

78.        --  container can destroy that widget. If you want to use Widget

79.        --  again, you need to add a reference to it while it's not inside

80.        --  a container, using Glib.Object.Ref. If you don't want to use Widget

81.        --  again it's usually more efficient to simply destroy it directly

82.        --  using Gtk.Widget.Destroy since this will remove it from the

83.        --  container and help break any circular reference count cycles.

85.        procedure Set_Resize_ModeTo API docTo body

86.          (Container   : access Gtk_Container_RecordTo API docTo specTo body;

87.           Resize_ModeTo API docTo body : Gtk.Enums.Gtk_Resize_ModeTo API docTo spec);

88.        function Get_Resize_ModeTo API docTo body

89.          (Container : access Gtk_Container_RecordTo API docTo specTo body)

90.           return Gtk.Enums.Gtk_Resize_ModeTo API docTo spec;

91.        --  Change the resizing behavior for the Container.

92.        --  The default value is Resize_Parent.

94.        function Get_ChildrenTo API docTo body

95.          (Container : access Gtk_Container_RecordTo API docTo specTo body)

96.           return Gtk.Widget.Widget_List.GlistTo API docTo specTo body;

97.        --  Return a list of all the children of the container.

98.        --  The caller must free the returned list.

100.        procedure Propagate_ExposeTo API docTo body

101.          (Container : access Gtk_Container_RecordTo API docTo specTo body;

102.           Child     : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class;

103.           Event     : Gdk.Event.Gdk_Event_ExposeTo API docTo spec);

104.        --  When a container receives an expose event, it must send synthetic

105.        --  expose events to all children that don't have their own Gdk_Window.

106.        --  This function provides a convenient way of doing this. A container,

107.        --  when it receives an expose event, Propagate_Expose

108.        --  once for each child, passing in the event the container received.

109.        --

110.        --  Propagate_Expose takes care of deciding whether

111.        --  an expose event needs to be sent to the child, intersecting

112.        --  the event's area with the child area, and sending the event.

113.        --

114.        --  In most cases, a container can simply either simply inherit the

115.        --  expose implementation from Gtk_Container, or, do some drawing

116.        --  and then chain to the expose implementation from Gtk_Container.

118.        -----------

119.        -- Focus --

120.        -----------

122.        procedure Set_Focus_ChainTo API docTo body

123.          (Container         : access Gtk_Container_RecordTo API docTo specTo body;

124.           Focusable_WidgetsTo API docTo body : Gtk.Widget.Widget_List.GlistTo API docTo specTo body);

125.        --  Set the chain of widgets that can take the focus for a given Container.

126.        --  The list should be freed by the user.

127.        --  This list indicates in which order the widgets will get the focus when

128.        --  the user presses tab or the arrow keys to move from one widget to the

129.        --  next.

131.        procedure Get_Focus_ChainTo API docTo body

132.          (Container         : access Gtk_Container_RecordTo API docTo specTo body;

133.           Focusable_WidgetsTo API docTo body : out Gtk.Widget.Widget_List.GlistTo API docTo specTo body;

134.           Success           : out Boolean);

135.        --  Retrieves the focus chain of the container, if one has been

136.        --  set explicitly. If no focus chain has been explicitly

137.        --  set, GTK+ computes the focus chain based on the positions

138.        --  of the children. In that case, GTK+ stores null in

139.        --  Focusable_Widgets and returns FALSE.

140.        --  The returned list must be freed by the user.

142.        procedure Unset_Focus_ChainTo API docTo body (Container : access Gtk_Container_RecordTo API docTo specTo body);

143.        --  Undoes the effect of Set_Focus_Chain

145.        procedure Set_Focus_VadjustmentTo API docTo body

146.          (Container  : access Gtk_Container_RecordTo API docTo specTo body;

147.           Adjustment : Gtk.Adjustment.Gtk_AdjustmentTo API docTo spec);

148.        function Get_Focus_VadjustmentTo API docTo body

149.          (Container : access Gtk_Container_RecordTo API docTo specTo body)

150.           return Gtk.Adjustment.Gtk_AdjustmentTo API docTo spec;

151.        --  Set the focus to the vertical adjustment.

152.        --  Adjustment should have been created and displayed at some other

153.        --  place in your application.

154.        --  Container will make sure that Adjustment always matches the range

155.        --  for the focus widget's position (y .. y + height).

157.        procedure Set_Focus_HadjustmentTo API docTo body

158.          (Container  : access Gtk_Container_RecordTo API docTo specTo body;

159.           Adjustment : Gtk.Adjustment.Gtk_AdjustmentTo API docTo spec);

160.        function Get_Focus_HadjustmentTo API docTo body

161.          (Container : access Gtk_Container_RecordTo API docTo specTo body)

162.           return Gtk.Adjustment.Gtk_AdjustmentTo API docTo spec;

163.        --  Set the focus to the horizontal adjustment.

164.        --  Adjustment should have been created and displayed at some other

165.        --  place in your application.

166.        --  Container will make sure that Adjustment always matches the range

167.        --  for the focus widget's position (x .. x + width).

169.        procedure Set_Focus_ChildTo API docTo body

170.          (Container : access Gtk_Container_RecordTo API docTo specTo body;

171.           Child     : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class);

172.        function Get_Focus_ChildTo API docTo body

173.          (Container : access Gtk_Container_RecordTo API docTo specTo body) return Gtk.Widget.Gtk_WidgetTo API docTo spec;

174.        --  Emit a "set_focus_child" signal, to set the child that currently has the

175.        --  keyboard focus.

177.        ----------------

178.        -- Properties --

179.        ----------------

181.        procedure Child_Set_PropertyTo API docTo body

182.          (Container     : access Gtk_Container_RecordTo API docTo specTo body;

183.           Child         : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class;

184.           Property_Name : String;

185.           ValueTo API docTo body         : Glib.Values.GValueTo API docTo specTo body);

186.        procedure Child_Get_PropertyTo API docTo body

187.          (Container     : access Gtk_Container_RecordTo API docTo specTo body;

188.           Child         : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class;

189.           Property_Name : String;

190.           ValueTo API docTo body         : out Glib.Values.GValueTo API docTo specTo body);

191.        --  Sets or Gets the value of a child property for Child and Container. This

192.        --  is property set at the container level, and that applies to all children

193.        --  of that container. These are special type of properties, different from

194.        --  the properties associated with each type of widget.

195.        --  See also Gtk.Widget.Child_Notify

196.        --  You should use Glib.Property_Name to get the name from the property

197.        --  declaration in each of the GtkAda packages

199.        function Class_Find_Child_PropertyTo API docTo body

200.          (Cclass        : Glib.Object.GObject_ClassTo API docTo spec;

201.           Property_Name : String) return Glib.Param_SpecTo API docTo spec;

202.        --  Finds a child property of a container class by name. The returned value

203.        --  describes the property (type, allowed range, description,...)

204.        --  You should use Glib.Property_Name to get the name from the property

205.        --  declaration in each of the GtkAda packages

207.        procedure Class_Install_Child_PropertyTo API docTo body

208.          (Cclass      : Glib.Object.GObject_ClassTo API docTo spec;

209.           Property_Id : GuintTo API docTo spec;

210.           Pspec       : Glib.Param_SpecTo API docTo spec);

211.        --  Installs a child property on a container class.

212.        --  The Property_Id is an custom id that you choose for your class. It will

213.        --  be used in signals that set or get the property, instead of passing

214.        --  around a string.

216.        function Class_List_Child_PropertiesTo API docTo body

217.          (Cclass : Glib.Object.GObject_ClassTo API docTo spec) return Glib.Param_Spec_ArrayTo API docTo spec;

218.        --  Returns all child properties of a container class.

220.        ----------------------

221.        -- Forall functions --

222.        ----------------------

224.        type Gtk_Callback is

225.          access procedure (Item : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class);

226.        --  Function that can be call for each child of a container.

227.        --  This is called automatically by the Forall subprogram below.

229.        procedure ForallTo API docTo body

230.          (Container : access Gtk_Container_RecordTo API docTo specTo body;

231.           Func      : Gtk_CallbackTo API docTo spec);

232.        --  Invokes Func on each child of Container, including children that are

233.        --  considered "internal" (implementation details of the container).

234.        --  "Internal" children generally weren't added by the user of the

235.        --  container, but were added by the container implementation itself. See

236.        --  Gtk.Widget.Set_Composite_Name.

237.        --  Most applications should use gtk_container_foreach(), rather than

238.        --  gtk_container_forall().

239.        --  See also the generic package Forall_Pkg if you want to pass some

240.        --  extra data to Func.

242.        procedure ForeachTo API docTo body

243.          (Container : access Gtk_Container_RecordTo API docTo specTo body;

244.           Func      : Gtk_CallbackTo API docTo spec);

245.        --  Invokes Func on each non-internal child of Container. See Forall for

246.        --  details on what constitutes an "internal" child.

248.        --  <doc_ignore>

249.        generic

250.           type Data_Type (<>) is private;

251.        package For_PkgTo API docTo body is

252.           type Gtk_Callback is

253.             access procedure (Item : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class;

254.                               Data : in out Data_TypeTo API docTo spec);

255.           procedure ForallTo API docTo body

256.             (Container : access Gtk_Container_RecordTo API docTo specTo body;

257.              Func      : Gtk_CallbackTo API docTo spec;

258.              Data      : Data_TypeTo API docTo spec);

259.           --  Execute Func for each of the children of Container, including

260.           --  internal ones

262.           procedure ForeachTo API docTo body

263.             (Container : access Gtk_Container_RecordTo API docTo specTo body;

264.              Func      : Gtk_CallbackTo API docTo spec;

265.              Data      : Data_TypeTo API docTo spec);

266.           --  Execute Func for each of the children of Container, not including

267.           --  internal ones

268.        end For_PkgTo API docTo specTo body;

269.        --  </doc_ignore>

271.        --------------------------

272.        -- Widget-level methods --

273.        --------------------------

275.        procedure Set_Reallocate_RedrawsTo API docTo body

276.          (Container     : access Gtk_Container_RecordTo API docTo specTo body;

277.           Needs_Redraws : Boolean := False);

278.        --  Set the "needs_redraws" field.

279.        --  If Needs_Redraws is True, then a "draw" signal is emitted for the

280.        --  Container whenever one is emitted for a child.

282.        function Child_TypeTo API docTo body

283.          (Container : access Gtk_Container_RecordTo API docTo specTo body) return Gtk.Gtk_TypeTo API docTo spec;

284.        --  Return the type of the children in Container.

285.        --  If Container can contain any type of widget, Gtk_Type_None is

286.        --  returned.

288.        procedure Resize_ChildrenTo API docTo body (Container : access Gtk_Container_RecordTo API docTo specTo body);

289.        --  The container hasn't changed size but one of its children

290.        --  queued a resize request. Which means that the allocation

291.        --  is not sufficient for the requisition of some child.

292.        --  Run through the list of widgets and reallocate their size appropriately.

294.        ----------------------

295.        -- Signals emission --

296.        ----------------------

298.        procedure Check_ResizeTo API docTo body (Container : access Gtk_Container_RecordTo API docTo specTo body);

299.        --  Emit the "check_resize" signal

301.        -----------------

302.        -- Obsolescent --

303.        -----------------

304.        --  All subprograms below are now obsolescent in gtk+. They might be removed

305.        --  from future versions of gtk+ (and therefore GtkAda).

306.        --  To find out whether your code uses any of these, we recommend compiling

307.        --  with the -gnatwj switch

308.        --  <doc_ignore>

310.        function Children

311.          (Container : access Gtk_Container_RecordTo API docTo specTo body)

312.           return Gtk.Widget.Widget_List.GlistTo API docTo specTo body

313.           renames Get_ChildrenTo API docTo specTo body;

314.        --  pragma Obsolescent;

316.        --  </doc_ignore>

318.        ----------------

319.        -- Properties --

320.        ----------------

322.        --  <properties>

323.        --  The following properties are defined for this widget. See

324.        --  Glib.Properties for more information on properties.

325.        --

326.        --  - Name:  Border_Width_Property

327.        --    Type:  Guint

328.        --    Flags: read-write

329.        --    Descr: The width of the empty border outside the containers children.

330.        --    See also:  Set_Border_Width

331.        --

332.        --  - Name:  Resize_Mode_Property

333.        --    Type:  Gtk_Resize_Mode

334.        --    Flags: read-write

335.        --    Descr: Specify how resize events are handled

336.        --    See also:  Set_Resize_Mode

337.        --

338.        --  - Name:  Child_Property

339.        --    Type:  Widget

340.        --    Flags: writable

341.        --    Descr: Can be used to add a new child to the container.

342.        --    See also:  Add

343.        --

344.        --  - Name:  Reallocate_Redraws_Property

345.        --    Type:  Boolean

346.        --    Flags: read-write

347.        --    Descr: Whether redraws should be reallocated

348.        --    See also: Set_Reallocate_Redraws

349.        --  </properties>

351.        Border_Width_Property       : constant Glib.Properties.Property_UintTo API docTo spec;

352.        Resize_Mode_Property        : constant Gtk.Enums.Property_Gtk_Resize_ModeTo API docTo spec;

353.        Child_Property              : constant Glib.Properties.Property_Object_WOTo API docTo spec;

354.        Reallocate_Redraws_Property : constant Glib.Properties.Property_BooleanTo API docTo spec;

356.        -------------

357.        -- Signals --

358.        -------------

360.        --  <signals>

361.        --  The following new signals are defined for this widget:

362.        --

363.        --  - "add"

364.        --    procedure Handler (Container : access Gtk_Container_Record'Class;

365.        --                       Widget    : access Gtk_Widget_Record'Class);

366.        --

367.        --    A new widget is added to the container

368.        --

369.        --  - "remove"

370.        --    procedure Handler (Container : access Gtk_Container_Record'Class;

371.        --                       Widget    : access Gtk_Widget_Record'Class);

372.        --

373.        --    A widget is removed from the container

374.        --

375.        --  - "check_resize"

376.        --    procedure Handler (Container : access Gtk_Container_Record'Class);

377.        --

378.        --    Called every time the Container needs resizing.

379.        --    Upon receiving this signal, Container should check whether it needs

380.        --    to be resized, and if it does should queue a resize request.

381.        --

382.        --  - "focus"

383.        --    procedure Handler (Container : access Gtk_Container_Record'Class;

384.        --                       Direction : Gtk_Direction_Type);

385.        --

386.        --    Moves the current selection to a new widget.

387.        --

388.        --  - "set-focus-child"

389.        --    procedure Handler (Container : access Gtk_Container_Record'Class;

390.        --                       Widget    : access Gtk_Widget_Record'Class);

391.        --

392.        --    Emitted when a new widget gains the focus.

393.        --

394.        --  </signals>

396.        Signal_Add             : constant Glib.Signal_NameTo API docTo spec := "add";

397.        Signal_Check_Resize    : constant Glib.Signal_NameTo API docTo spec := "check_resize";

398.        Signal_Remove          : constant Glib.Signal_NameTo API docTo spec := "remove";

399.        Signal_Set_Focus_Child : constant Glib.Signal_NameTo API docTo spec := "set-focus-child";

401.     private

402.        type Gtk_Container_RecordTo API docTo spec is new Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body

403.          with null record;

405.        Border_Width_PropertyTo API docTo spec       : constant Glib.Properties.Property_UintTo API docTo spec :=

406.          Glib.Properties.BuildTo API docTo specTo body ("border_width");

407.        Resize_Mode_PropertyTo API docTo spec        : constant Gtk.Enums.Property_Gtk_Resize_ModeTo API docTo spec :=

408.          Gtk.Enums.BuildTo API docTo specTo body ("resize_mode");

409.        Child_PropertyTo API docTo spec              : constant Glib.Properties.Property_Object_WOTo API docTo spec :=

410.          Glib.Properties.BuildTo API docTo specTo body ("child");

411.        Reallocate_Redraws_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

412.          Glib.Properties.BuildTo API docTo specTo body ("reallocate_redraws");

414.        pragma Import (C, Get_TypeTo API docTo spec, "gtk_container_get_type");

415.     end Gtk.ContainerTo API docTo specTo body;

417.     --  No binding: gtk_container_child_get_valist

418.     --  No binding: gtk_container_child_set_valist

419.     --  No binding: gtk_container_child_set

420.     --  No binding: gtk_container_child_get

421.     --  No binding: gtk_container_add_with_properties

423.     --  These functions never had a binding, but are now obsolescent

424.     --  No binding: gtk_container_foreach_full

426.     --  Bound using C glue function:

427.     --  No binding: gtk_container_get_focus_child