## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

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

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

3.     --                                                                   --

4.     --                 Copyright (C) 2003-2010, 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.     --  This widget implements a multi-paned widget, similar to the standard

31.     --  Gtk_Paned widget, but which can contain several children side to side.

32.     --  This widget can mix vertical and horizontal splits

33.     --  </description>

34.     --  <group>Layout containers</group>

35.     --  <testgtk>create_splittable.adb</testgtk>

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

38.     with Gdk.CursorTo API docTo specTo body;

39.     with Gdk.GCTo API docTo specTo body;

40.     with Gtk.EnumsTo API docTo specTo body;

41.     with Gtk.FixedTo API docTo specTo body;

42.     with Gtk.WidgetTo API docTo specTo body;

44.     package Gtkada.Multi_PanedTo API docTo specTo body is

45.        type Gtkada_Multi_Paned_RecordTo API docTo body is new Gtk.Fixed.Gtk_Fixed_RecordTo API docTo spec

46.          with private;

47.        type Gtkada_Multi_Paned is access all Gtkada_Multi_Paned_RecordTo API docTo specTo body'Class;

49.        Handle_Width : constant := 6;

50.        --  Width, in pixels, of the resizing handles.

51.        --  ??? Should be read from theme with

52.        --     gtk_widget_style_get (gtk_paned, "handle_size", &handle_size, NULL)

54.        type Pane is private;

55.        --  An area of the window, which can is splitted either horizontally or

56.        --  vertically. It can contain one or several children, next to each other,

57.        --  or on top of one another.

59.        Root_Pane : constant PaneTo API docTo spec;

60.        --  The root pane. If you split this one, the newly added window will be

61.        --  next to all other windows. For instance, if you split vertically with

62.        --  the main_pane the following window, you will get:

63.        --     +-----+------+        +-----+------+

64.        --     |  1  |      |        |  1  |      |

65.        --     +-----+  3   |    =>  +-----+  3   |

66.        --     |  2  |      |        |  2  |      |

67.        --     +-----+------+        +-----+------+

68.        --                           |     4      |

69.        --                           +------------+

71.        procedure Gtk_NewTo API docTo body (Win : out Gtkada_Multi_PanedTo API docTo spec);

72.        procedure InitializeTo API docTo body (Win : access Gtkada_Multi_Paned_RecordTo API docTo specTo body'Class);

73.        --  Create a new paned window.

75.        procedure Set_Opaque_ResizingTo API docTo body

76.          (Win : access Gtkada_Multi_Paned_RecordTo API docTo specTo body; Opaque : Boolean);

77.        --  Whether resizing of the widgets should be opaque or not. The default

78.        --  is not to do opaque resizing for efficiency reasons

80.        procedure Add_ChildTo API docTo body

81.          (Win           : access Gtkada_Multi_Paned_RecordTo API docTo specTo body;

82.           New_Child     : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class;

83.           OrientationTo API docTo body   : Gtk.Enums.Gtk_OrientationTo API docTo spec :=

84.             Gtk.Enums.Orientation_Horizontal;

85.           Fixed_Size    : Boolean := False;

86.           Width, Height : Glib.GintTo API docTo spec := -1;

87.           After         : Boolean := True);

88.        --  Add new child, splitting as needed.

89.        --  This should be used when there is no child yet

90.        --  The window is splitted in two by default. However, if Width and Height

91.        --  are specified (or left to -1 for automatic computation), the window is

92.        --  splitted so that amount of screen space is left to the widget

93.        --  (leaving some minimum amount of space to other children as needed).

94.        --  If Fixed_Size is true, then the size of the dock will not change when

95.        --  Win is resized. Otherwise, it will keep its relative size (x% of the

96.        --  total size of Win). This Fixed_Size setting will be reset to False

97.        --  as soon as the user has resized a pane with the mouse.

99.        procedure SplitTo API docTo body

100.          (Win           : access Gtkada_Multi_Paned_RecordTo API docTo specTo body;

101.           Ref_Widget    : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class;

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

103.           OrientationTo API docTo body   : Gtk.Enums.Gtk_OrientationTo API docTo spec;

104.           Fixed_Size    : Boolean := False;

105.           Width, Height : Glib.GintTo API docTo spec := -1;

106.           After         : Boolean := True);

107.        --  Split the pane containing Ref_Widget, and add New_Child

108.        --  in the new pane (on the right or at the bottom if After is True, on the

109.        --  left or at the top if After is False).

111.        procedure Set_SizeTo API docTo body

112.          (Win           : access Gtkada_Multi_Paned_RecordTo API docTo specTo body;

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

114.           Width, Height : Glib.GintTo API docTo spec := -1;

115.           Fixed_Size    : Boolean := False);

116.        --  Force a specific size for Widget

118.        function Splitted_AreaTo API docTo body

119.          (Win           : access Gtkada_Multi_Paned_RecordTo API docTo specTo body;

120.           Ref_Widget    : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class;

121.           OrientationTo API docTo body   : Gtk.Enums.Gtk_OrientationTo API docTo spec;

122.           After         : Boolean := True) return Gtk.Widget.Gtk_WidgetTo API docTo spec;

123.        --  Return the widget in the splitted area next to Ref_Widget if any exist.

124.        --  Orientation and After define which splitted area we are looking at.

125.        --  null is returned if there are no such splitted area.

127.        function Get_PaneTo API docTo body

128.          (Win    : access Gtkada_Multi_Paned_RecordTo API docTo specTo body;

129.           Widget : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class) return PaneTo API docTo spec;

130.        function Get_PaneTo API docTo body (Current_Pane : PaneTo API docTo spec) return PaneTo API docTo spec;

131.        --  Return the pane that contains the widget. See comment for Split below.

133.        procedure SplitTo API docTo body

134.          (Win           : access Gtkada_Multi_Paned_RecordTo API docTo specTo body;

135.           Ref_Pane      : PaneTo API docTo spec;

136.           New_Child     : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class;

137.           OrientationTo API docTo body   : Gtk.Enums.Gtk_OrientationTo API docTo spec;

138.           Fixed_Size    : Boolean := False;

139.           Width, Height : Glib.GintTo API docTo spec := -1;

140.           After         : Boolean := True);

141.        --  Split Ref_Pane to display New_Child to one of its sides.

142.        --  See the comments for Root_Pane above.

143.        --  The examples below assume that you are using one of the two split

144.        --  procedures, either with a Ref_Pane or a Ref_Widget. In the former case,

145.        --  the pane is obtained with a call to Get_Pane(Ref_Widget).

146.        --  As you will see, the results are different (although they might appear

147.        --  similar sometimes on this simple example.

148.        --  In all these examples, we split either vertically or horizontally, and

149.        --  add a new widget "4".

150.        --

151.        --  Given the following setup:

152.        --     +---+---+

153.        --     | 1 |   |

154.        --     +---+ 3 |

155.        --     | 2 |   |

156.        --     +---+---+

157.        --

158.        --  Ref_Pane = Get_Pane ("1")              Ref_Widget = "1"

159.        --  Split vertically

160.        --    After=True  After=False        After=True   After=False

161.        --    +---+---+   +---+---+          +---+---+    +---+---+

162.        --    | 1 | 3 |   | 4 | 3 |          | 1 | 3 |    | 4 | 3 |

163.        --    +---+   |   +---+   |          +---+   |    +---+   |

164.        --    | 2 |   |   | 1 |   |          | 4 |   |    | 1 |   |

165.        --    +---+   |   +---+   |          +---+   |    +---+   |

166.        --    | 4 |   |   | 2 |   |          | 2 |   |    | 2 |   |

167.        --    +---+---+   +---+---+          +---+---+    +---+---+

168.        --

169.        --  Split horizontally

170.        --    After=True     After=False     After=True     After=False

171.        --    +---+---+---+  +---+---+---+   +---+---+---+  +---+---+---+

172.        --    | 1 | 4 | 3 |  | 4 | 1 | 3 |   | 1 | 4 | 3 |  | 4 | 1 | 3 |

173.        --    +---+   |   |  |   +---+   |   +---+---+   |  +---+---+   |

174.        --    | 2 |   |   |  |   | 2 |   |   |   2   |   |  |   2   |   |

175.        --    +---+---+---+  +---+---+---+   +-------+---+  +-------+---+

176.        --

177.        --

178.        --  Ref_Pane = Get_Pane ("3")             Ref_Widget = "3"

179.        --  Split vertically

180.        --    After=True   After=False       After=True     After=False

181.        --    +---+---+    +-------+         +---+---+      +---+---+

182.        --    | 1 | 3 |    |   4   |         | 1 | 3 |      | 1 | 4 |

183.        --    +---+   |    +---+---+         +---+---+      +---+---+

184.        --    | 2 |   |    | 1 | 3 |         | 2 | 4 |      | 2 | 3 |

185.        --    +---+---+    +---+   |         +---+---+      +---+---+

186.        --    |   4   |    | 2 |   |

187.        --    +-------+    +---+---+

188.        --

189.        --  Split horizontally

190.        --    After=True     After=False     After=True     After=False

191.        --    +---+---+---+  +---+---+---+   +---+---+---+  +---+---+---+

192.        --    | 1 | 3 | 4 |  | 4 | 1 | 3 |   | 1 | 3 | 4 |  | 1 | 4 | 3 |

193.        --    +---+   |   |  |   +---+   |   +---+   |   |  +---+   |   |

194.        --    | 2 |   |   |  |   | 2 |   |   | 2 |   |   |  | 2 |   |   |

195.        --    +---+---+---+  +---+---+---+   +---+---+---+  +---+---+---+

197.        procedure FreezeTo API docTo body (Win : access Gtkada_Multi_Paned_RecordTo API docTo specTo body);

198.        --  Freeze the window, ie when a child is inserted, no computation of its

199.        --  size is done, and will not generate immediate resizing.

200.        --  You only need to call this procedure when restoring Win to a previously

201.        --  state saved, and never if you are using the GtkAda.MDI which takes care

202.        --  of it on its own.

204.        procedure ThawTo API docTo body (Win : access Gtkada_Multi_Paned_RecordTo API docTo specTo body);

205.        --  Opposite of Freeze. You should call Size_Allocate on Win afterward to

206.        --  force a recomputation of the size

208.        ---------------

209.        -- Iterators --

210.        ---------------

212.        type Child_IteratorTo API docTo body is private;

214.        function StartTo API docTo body

215.          (Win : access Gtkada_Multi_Paned_RecordTo API docTo specTo body) return Child_IteratorTo API docTo specTo body;

216.        --  Return an iterator to the first child of the window. This also returns

217.        --  children which are not widget, but are used to organize the window into

218.        --  horizontal and vertical panes

220.        function At_EndTo API docTo body (IterTo API docTo body : Child_IteratorTo API docTo specTo body) return Boolean;

221.        --  True if there is no more child to be returned

223.        procedure NextTo API docTo body (IterTo API docTo body : in out Child_IteratorTo API docTo specTo body);

224.        --  Move to the next child of Iterator

226.        function Get_WidgetTo API docTo body (IterTo API docTo body : Child_IteratorTo API docTo specTo body) return Gtk.Widget.Gtk_WidgetTo API docTo spec;

227.        --  Return the widget embedded in the current child. This returns null if

228.        --  the current child is only used as a pane separator (horizontal or

229.        --  vertical). You mustn't remove the widget from the paned widget, or the

230.        --  iterator becomes invalid.

232.        function Get_OrientationTo API docTo body

233.          (IterTo API docTo body : Child_IteratorTo API docTo specTo body) return Gtk.Enums.Gtk_OrientationTo API docTo spec;

234.        --  Return the orientation of the current child. This is only relevant if

235.        --  the child doesn't contain a widget (and therefore Get_Widget has

236.        --  returned null).

238.        function Get_DepthTo API docTo body (IterTo API docTo body : Child_IteratorTo API docTo specTo body) return Natural;

239.        --  Return the depth of the current child (0 means the child is at the

240.        --  toplevel, 1 that this is a child directly underneath,...).

241.        --  This can be used to detect when the Iter has finished traversing one

242.        --  of the panes.

244.        procedure Get_SizeTo API docTo body

245.          (IterTo API docTo body                        : Child_IteratorTo API docTo specTo body;

246.           Width, Height               : out GintTo API docTo spec;

247.           Parent_Width, Parent_Height : out GintTo API docTo spec;

248.           Parent_OrientationTo API docTo body          : out Gtk.Enums.Gtk_OrientationTo API docTo spec);

249.        --  Return the size of the current element (pane or widget), as well as the

250.        --  parent's pane (the resizable area that contains notebooks or other

251.        --  panes). The parent size is the total size devoted to its children,

252.        --  omitting the size occupied by resize handles.

254.        procedure DumpTo API docTo body (Split : access Gtkada_Multi_Paned_RecordTo API docTo specTo body'Class);

255.        --  Dump the configuration of Split to stdout. This is only intended for

256.        --  testing purposes. If you want to save and restore this configuration,

257.        --  you should look at Gtkada.MDI instead, which contains all the

258.        --  subprograms needed to handle desktops.

260.     private

261.        type Child_Description;

262.        type Child_Description_Access is access Child_Description;

264.        type PaneTo API docTo spec is new Child_Description_Access;

265.        Root_PaneTo API docTo spec : constant PaneTo API docTo spec := null;

267.        type Child_IteratorTo API docTo spec is record

268.           Current : Child_Description_Access;

269.           Depth   : Natural := 0;

270.        end record;

272.        type Gtkada_Multi_Paned_RecordTo API docTo spec is new Gtk.Fixed.Gtk_Fixed_RecordTo API docTo spec with record

273.           Frozen      : Boolean := False;

274.           Children    : Child_Description_Access;

275.           GC          : Gdk.GC.Gdk_GCTo API docTo spec;

277.           Initial_Pos  : GintTo API docTo spec;

278.           Selected     : Child_Description_Access;

279.           Selected_Pos : Gtk.Widget.Gtk_AllocationTo API docTo spec;

281.           Cursor_Double_H_Arrow : Gdk.Cursor.Gdk_CursorTo API docTo spec;

282.           Cursor_Double_V_Arrow : Gdk.Cursor.Gdk_CursorTo API docTo spec;

284.           Opaque_Resizing        : Boolean := False;

285.        end record;

287.     end Gtkada.Multi_PanedTo API docTo specTo body;