## 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-2011, 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.     --  A Gtk_Assistant is a widget used to represent a generally complex

32.     --  operation split into several steps, guiding the user through its pages and

33.     --  controlling the page flow to collect the necessary data.

34.     --

35.     --  </description>

36.     --  <group>Windows</group>

37.     --  <testgtk>create_assistant.adb</testgtk>

39.     pragma Warnings (Off, "*is already use-visible*");

40.     with Gdk.PixbufTo API docTo specTo body;    use Gdk.PixbufTo API docTo specTo body;

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

42.     with Glib.TypesTo API docTo specTo body;    use Glib.TypesTo API docTo specTo body;

43.     with Gtk.BuildableTo API docTo specTo body; use Gtk.BuildableTo API docTo specTo body;

44.     with Gtk.WidgetTo API docTo specTo body;    use Gtk.WidgetTo API docTo specTo body;

45.     with Gtk.WindowTo API docTo specTo body;    use Gtk.WindowTo API docTo specTo body;

47.     package Gtk.AssistantTo API docTo specTo body is

49.        type Gtk_Assistant_Record is new Gtk_Window_RecordTo API docTo specTo body with null record;

50.        type Gtk_Assistant is access all Gtk_Assistant_RecordTo API docTo spec'Class;

52.        type Gtk_Assistant_Page_Type is

53.             (Gtk_Assistant_Page_Content,

54.              Gtk_Assistant_Page_Intro,

55.              Gtk_Assistant_Page_Confirm,

56.              Gtk_Assistant_Page_Summary,

57.              Gtk_Assistant_Page_Progress);

58.           --  Definition of various page types.  See Get_Page_Type/Set_Page_Type

59.           --  for more info.

61.           type Gtk_Assistant_Page_Func is access function

62.             (Current_Page : GintTo API docTo spec;

63.              D : System.Address) return GintTo API docTo spec;

64.           pragma Convention (C, Gtk_Assistant_Page_FuncTo API docTo spec);

66.        ------------------

67.        -- Constructors --

68.        ------------------

70.        procedure Gtk_NewTo API docTo body (Assistant : out Gtk_AssistantTo API docTo spec);

71.        procedure InitializeTo API docTo body (Assistant : access Gtk_Assistant_RecordTo API docTo spec'Class);

72.        --  Creates a new Gtk.Assistant.Gtk_Assistant.

73.        --  Since: gtk+ 2.10

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

76.        pragma Import (C, Get_TypeTo API docTo spec, "gtk_assistant_get_type");

78.        -------------

79.        -- Methods --

80.        -------------

82.        procedure Add_Action_WidgetTo API docTo body

83.           (Assistant : access Gtk_Assistant_RecordTo API docTo spec;

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

85.        --  Adds a widget to the action area of a Gtk.Assistant.Gtk_Assistant.

86.        --  Since: gtk+ 2.10

87.        --  "child": a Gtk.Widget.Gtk_Widget

89.        function Append_PageTo API docTo body

90.           (Assistant : access Gtk_Assistant_RecordTo API docTo spec;

91.            Page      : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class) return GintTo API docTo spec;

92.        --  Appends a page to the Assistant.

93.        --  Since: gtk+ 2.10

94.        --  "page": a Gtk.Widget.Gtk_Widget

96.        procedure CommitTo API docTo body (Assistant : access Gtk_Assistant_RecordTo API docTo spec);

97.        --  Erases the visited page history so the back button is not shown on the

98.        --  current page, and removes the cancel button from subsequent pages. Use

99.        --  this when the information provided up to the current page is hereafter

100.        --  deemed permanent and cannot be modified or undone. For example, showing

101.        --  a progress page to track a long-running, unreversible operation after

102.        --  the user has clicked apply on a confirmation page.

103.        --  Since: gtk+ 2.22

105.        function Get_Current_PageTo API docTo body

106.           (Assistant : access Gtk_Assistant_RecordTo API docTo spec) return GintTo API docTo spec;

107.        procedure Set_Current_PageTo API docTo body

108.           (Assistant : access Gtk_Assistant_RecordTo API docTo spec;

109.            Page_Num  : GintTo API docTo spec);

110.        --  Switches the page to Page_Num. Note that this will only be necessary in

111.        --  custom buttons, as the Assistant flow can be set with

112.        --  Gtk.Assistant.Set_Forward_Page_Func.

113.        --  Since: gtk+ 2.10

114.        --  "page_num": index of the page to switch to, starting from 0. If

115.        --  negative, the last page will be used. If greater than the number of

116.        --  pages in the Assistant, nothing will be done.

118.        function Get_N_PagesTo API docTo body

119.           (Assistant : access Gtk_Assistant_RecordTo API docTo spec) return GintTo API docTo spec;

120.        --  Returns the number of pages in the Assistant

121.        --  Since: gtk+ 2.10

123.        function Get_Nth_PageTo API docTo body

124.           (Assistant : access Gtk_Assistant_RecordTo API docTo spec;

125.            Page_Num  : GintTo API docTo spec) return Gtk.Widget.Gtk_WidgetTo API docTo spec;

126.        --  Returns the child widget contained in page number Page_Num. if Page_Num

127.        --  is out of bounds.

128.        --  Since: gtk+ 2.10

129.        --  "page_num": The index of a page in the Assistant, or -1 to get the last

130.        --  page;

132.        function Get_Page_CompleteTo API docTo body

133.           (Assistant : access Gtk_Assistant_RecordTo API docTo spec;

134.            Page      : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class) return Boolean;

135.        procedure Set_Page_CompleteTo API docTo body

136.           (Assistant : access Gtk_Assistant_RecordTo API docTo spec;

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

138.            Complete  : Boolean);

139.        --  Sets whether Page contents are complete. This will make

140.        --  Since: gtk+ 2.10

141.        --  "page": a page of Assistant

142.        --  "complete": the completeness status of the page

144.        function Get_Page_Header_ImageTo API docTo body

145.           (Assistant : access Gtk_Assistant_RecordTo API docTo spec;

146.            Page      : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class)

147.            return Gdk.Pixbuf.Gdk_PixbufTo API docTo spec;

148.        procedure Set_Page_Header_ImageTo API docTo body

149.           (Assistant : access Gtk_Assistant_RecordTo API docTo spec;

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

151.            Pixbuf    : access Gdk.Pixbuf.Gdk_Pixbuf_RecordTo API docTo specTo body'Class);

152.        --  Sets a header image for Page. This image is displayed in the header

153.        --  area of the assistant when Page is the current page.

154.        --  Since: gtk+ 2.10

155.        --  "page": a page of Assistant

156.        --  "pixbuf": the new header image Page

158.        function Get_Page_Side_ImageTo API docTo body

159.           (Assistant : access Gtk_Assistant_RecordTo API docTo spec;

160.            Page      : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class)

161.            return Gdk.Pixbuf.Gdk_PixbufTo API docTo spec;

162.        procedure Set_Page_Side_ImageTo API docTo body

163.           (Assistant : access Gtk_Assistant_RecordTo API docTo spec;

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

165.            Pixbuf    : access Gdk.Pixbuf.Gdk_Pixbuf_RecordTo API docTo specTo body'Class);

166.        --  Sets a header image for Page. This image is displayed in the side area

167.        --  of the assistant when Page is the current page.

168.        --  Since: gtk+ 2.10

169.        --  "page": a page of Assistant

170.        --  "pixbuf": the new header image Page

172.        function Get_Page_TitleTo API docTo body

173.           (Assistant : access Gtk_Assistant_RecordTo API docTo spec;

174.            Page      : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class)

175.            return UTF8_StringTo API docTo spec;

176.        procedure Set_Page_TitleTo API docTo body

177.           (Assistant : access Gtk_Assistant_RecordTo API docTo spec;

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

179.            Title     : UTF8_StringTo API docTo spec);

180.        --  Sets a title for Page. The title is displayed in the header area of the

181.        --  assistant when Page is the current page.

182.        --  Since: gtk+ 2.10

183.        --  "page": a page of Assistant

184.        --  "title": the new title for Page

186.        function Get_Page_TypeTo API docTo body

187.           (Assistant : access Gtk_Assistant_RecordTo API docTo spec;

188.            Page      : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class)

189.            return Gtk_Assistant_Page_TypeTo API docTo spec;

190.        procedure Set_Page_TypeTo API docTo body

191.           (Assistant : access Gtk_Assistant_RecordTo API docTo spec;

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

193.            The_TypeTo API docTo body  : Gtk_Assistant_Page_TypeTo API docTo spec);

194.        --  Sets the page type for Page. The page type determines the page behavior

195.        --  in the Assistant.

196.        --  Since: gtk+ 2.10

197.        --  "page": a page of Assistant

198.        --  "type": the new type for Page

200.        function Insert_PageTo API docTo body

201.           (Assistant : access Gtk_Assistant_RecordTo API docTo spec;

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

203.            Position  : GintTo API docTo spec) return GintTo API docTo spec;

204.        --  Inserts a page in the Assistant at a given position.

205.        --  Since: gtk+ 2.10

206.        --  "page": a Gtk.Widget.Gtk_Widget

207.        --  "position": the index (starting at 0) at which to insert the page, or

208.        --  -1 to append the page to the Assistant

210.        function Prepend_PageTo API docTo body

211.           (Assistant : access Gtk_Assistant_RecordTo API docTo spec;

212.            Page      : access Gtk.Widget.Gtk_Widget_RecordTo API docTo specTo body'Class) return GintTo API docTo spec;

213.        --  Prepends a page to the Assistant.

214.        --  Since: gtk+ 2.10

215.        --  "page": a Gtk.Widget.Gtk_Widget

217.        procedure Remove_Action_WidgetTo API docTo body

218.           (Assistant : access Gtk_Assistant_RecordTo API docTo spec;

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

220.        --  Removes a widget from the action area of a Gtk.Assistant.Gtk_Assistant.

221.        --  Since: gtk+ 2.10

222.        --  "child": a Gtk.Widget.Gtk_Widget

224.        procedure Set_Forward_Page_FuncTo API docTo body

225.           (Assistant : access Gtk_Assistant_RecordTo API docTo spec;

226.            Page_Func : Gtk_Assistant_Page_FuncTo API docTo spec;

227.            Data      : System.Address;

228.            Destroy   : Glib.G_Destroy_Notify_AddressTo API docTo spec);

229.        --  Sets the page forwarding function to be Page_Func, this function will

230.        --  be used to determine what will be the next page when the user presses

231.        --  the forward button. Setting Page_Func to null will make the assistant to

232.        --  use the default forward function, which just goes to the next visible

233.        --  page.

234.        --  Since: gtk+ 2.10

235.        --  "page_func": the Gtk_Assistant_Page_Func, or null to use the default

236.        --  one

237.        --  "data": user data for Page_Func

238.        --  "destroy": destroy notifier for Data

240.        procedure Update_Buttons_StateTo API docTo body (Assistant : access Gtk_Assistant_RecordTo API docTo spec);

241.        --  Forces Assistant to recompute the buttons state. GTK+ automatically

242.        --  takes care of this in most situations, e.g. when the user goes to a

243.        --  different page, or when the visibility or completeness of a page

244.        --  changes. One situation where it can be necessary to call this function

245.        --  is when changing a value on the current page affects the future page

246.        --  flow of the assistant.

247.        --  Since: gtk+ 2.10

249.        ----------------------

250.        -- GtkAda additions --

251.        ----------------------

253.        generic

254.        type Data_Type (<>) is private;

255.        package Generic_Assistant_FunctionsTo API docTo body is

256.           type Page_Func is access function

257.             (Current_Page : GintTo API docTo spec;

258.              User_Data    : Data_TypeTo API docTo spec)

259.           return GintTo API docTo spec;

260.           --  Spec for page forwarding function.

262.           type Destroy_Notify is access procedure (User_Data : in out Data_TypeTo API docTo spec);

263.           --  Destroy_Notify is called just prior to the destruction of

264.           --  User_Data.

266.           procedure Set_Forward_Page_FuncTo API docTo body

267.             (Assistant : Gtk_AssistantTo API docTo spec;

268.              Func      : Page_FuncTo API docTo spec;

269.              User_Data : Data_TypeTo API docTo spec;

270.              Destroy   : Destroy_NotifyTo API docTo spec := null);

271.           --  Sets the Assistant's page forwarding function to be Func.  This

272.           --  function will be used to determine what will be the next page when

273.           --  the user presses the forward button. Setting Func to null will make

274.           --  the assistant use the default forward function, which just goes

275.           --  to the next visible page.

276.        end Generic_Assistant_FunctionsTo API docTo specTo body;

278.        ----------------

279.        -- Interfaces --

280.        ----------------

281.        --  This class implements several interfaces. See Glib.Types

282.        --

283.        --  - "Buildable"

285.        package Implements_Buildable is new Glib.Types.ImplementsTo API docTo specTo body

286.          (Gtk.Buildable.Gtk_BuildableTo API docTo spec, Gtk_Assistant_RecordTo API docTo spec, Gtk_AssistantTo API docTo spec);

287.        function "+"

288.          (Widget : access Gtk_Assistant_RecordTo API docTo spec'Class)

289.        return Gtk.Buildable.Gtk_BuildableTo API docTo spec

290.        renames Implements_Buildable.To_InterfaceTo API docTo specTo body;

291.        function "-"

292.          (Interf : Gtk.Buildable.Gtk_BuildableTo API docTo spec)

293.        return Gtk_AssistantTo API docTo spec

294.        renames Implements_Buildable.To_ObjectTo API docTo specTo body;

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

297.        -- Signals --

298.        -------------

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

300.        --

301.        --  "apply"

302.        --     procedure Handler (Self : access Gtk_Assistant_Record'Class);

303.        --  The ::apply signal is emitted when the apply button is clicked. The

304.        --  default behavior of the Gtk.Assistant.Gtk_Assistant is to switch to the

305.        --  page after the current page, unless the current page is the last one. A

306.        --  handler for the ::apply signal should carry out the actions for which

307.        --  the wizard has collected data. If the action takes a long time to

308.        --  complete, you might consider putting a page of type

309.        --  %GTK_ASSISTANT_PAGE_PROGRESS after the confirmation page and handle this

310.        --  operation within the Gtk.Assistant.Gtk_Assistant::prepare signal of the

311.        --  progress page.

312.        --

313.        --  "cancel"

314.        --     procedure Handler (Self : access Gtk_Assistant_Record'Class);

315.        --  The ::cancel signal is emitted when then the cancel button is clicked.

316.        --

317.        --  "close"

318.        --     procedure Handler (Self : access Gtk_Assistant_Record'Class);

319.        --  The ::close signal is emitted either when the close button of a summary

320.        --  page is clicked, or when the apply button in the last page in the flow

321.        --  (of type %GTK_ASSISTANT_PAGE_CONFIRM) is clicked.

322.        --

323.        --  "prepare"

324.        --     procedure Handler

325.        --       (Self : access Gtk_Assistant_Record'Class;

326.        --        Page : Gtk.Widget.Gtk_Widget);

327.        --    --  "page": the current page

328.        --  The ::prepare signal is emitted when a new page is set as the

329.        --  assistant's current page, before making the new page visible. A handler

330.        --  for this signal can do any preparation which are necessary before

331.        --  showing Page.

333.        Signal_Apply : constant Glib.Signal_NameTo API docTo spec := "apply";

334.        Signal_Cancel : constant Glib.Signal_NameTo API docTo spec := "cancel";

335.        Signal_Close : constant Glib.Signal_NameTo API docTo spec := "close";

336.        Signal_Prepare : constant Glib.Signal_NameTo API docTo spec := "prepare";

338.     end Gtk.AssistantTo API docTo specTo body;