## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

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

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

3.     --                                                                   --

4.     --                    Copyright (C) 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 package provides a ready-to-use high level printing object.

31.     --  Use functionality from Gtk.Print_Operation to manipulate the

32.     --  printing object, and the functionality in this package to provide

33.     --  the handlers for the printing operation.

34.     --

35.     --  Typically, to use this high-level printing API:

36.     --    - derive from the Gtkada_Print_Operation_Record object

37.     --    - override the Draw_Page operation

38.     --    - (optional) override any other operation useful to you

39.     --    - start the print operation by

40.     --          - first setting the number of pages through Set_N_Pages

41.     --          - then calling Connect_And_Run.

42.     --  A dialog will be displayed, letting the user select a printer and options.

43.     --  When the user finishes the dialog, various signals will be emitted on the

44.     --  Gtkada_Print_Operation, which will call the operations on your object.

45.     --

46.     --  Note: on UNIX/Linux, Gtk+ is loading at run-time the libraries for printing

47.     --  support. You will need to point the environment variable GTK_EXE_PREFIX

48.     --  to the root directory of your Gtk+ install before calling Connect_And_Run.

49.     --  </description>

50.     --  <example>

51.     --

52.     --     --  Create a derived type

53.     --

54.     --     type Print_Op_Record is new Gtkada_Print_Operation_Record

55.     --     with record

56.     --        My_Data : My_Type;

57.     --     end record;

58.     --     type Print_Op_Access is access all Print_Op_Record'Class;

59.     --

60.     --     --  Override Draw_Page

61.     --

62.     --     procedure Draw_Page

63.     --       (Print_Operation : access Print_Op_Record;

64.     --        Context         : Gtk_Print_Context;

65.     --        Page_Num        : Gint)

66.     --     is

67.     --        Cr : Cairo_Context;

68.     --     begin

69.     --        Cr := Get_Cairo_Context (Context);

70.     --

71.     --        --  Do drawing here

72.     --

73.     --     end Draw_Page;

74.     --

75.     --

76.     --     --  Do the printing

77.     --     declare

78.     --        Print_Op : Print_Op_Access;

79.     --        Result   : Gtk_Print_Operation_Result;

80.     --     begin

81.     --        --  Initialize

82.     --        Print_Op := new Print_Op_Record;

83.     --        Print_Op.My_Data := Some_Data;

84.     --

85.     --        --  Set the number of pages to print

86.     --        Set_N_Pages (Print_Op, 2);

87.     --

88.     --        --  Launch the printing

89.     --        Result := Connect_And_Run

90.     --          (Print_Op, Action_Print_Dialog, Gtk_Window (Get_Toplevel (Frame)));

91.     --     end;

92.     --

93.     --  </example>

94.     --  <group>Miscellaneous</group>

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

97.     with Glib.ErrorTo API docTo specTo body;

99.     with Gtk.Page_SetupTo API docTo specTo body;              use Gtk.Page_SetupTo API docTo specTo body;

100.     with Gtk.Print_ContextTo API docTo specTo body;           use Gtk.Print_ContextTo API docTo specTo body;

101.     with Gtk.Print_OperationTo API docTo specTo body;         use Gtk.Print_OperationTo API docTo specTo body;

102.     with Gtk.Print_Operation_PreviewTo API docTo specTo body; use Gtk.Print_Operation_PreviewTo API docTo specTo body;

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

105.     package Gtkada.PrintingTo API docTo specTo body is

107.        type Gtkada_Print_Operation_RecordTo API docTo body is new

108.          Gtk_Print_Operation_RecordTo API docTo specTo body with private;

109.        type Gtkada_Print_Operation is access all Gtkada_Print_Operation_RecordTo API docTo specTo body;

111.        procedure Gtk_NewTo API docTo body (Op : out Gtkada_Print_OperationTo API docTo spec);

112.        procedure InitializeTo API docTo body (Widget : access Gtkada_Print_Operation_RecordTo API docTo specTo body'Class);

113.        --  Initialize the print operation

115.        function Connect_And_RunTo API docTo body

116.          (Op        : access Gtkada_Print_Operation_RecordTo API docTo specTo body'Class;

117.           ActionTo API docTo body    : Gtk_Print_Operation_ActionTo API docTo spec;

118.           Parent    : access Gtk_Window_RecordTo API docTo specTo body'Class;

119.           Error     : Glib.Error.GErrorTo API docTo spec := null)

120.           return Gtk_Print_Operation_ResultTo API docTo spec;

121.        --  Runs the print operation, using the handlers installed in Op.

122.        --  See Gtk.Print_Operations.Run.

124.        -------------------------

125.        -- Printing operations --

126.        -------------------------

128.        --  The following primitive operations are called by the printing procedure.

129.        --  By default, these operations do nothing.

130.        --  It is mandatory to override Draw_Page, the other callbacks are optional.

132.        procedure Draw_PageTo API docTo body

133.          (Op          : access Gtkada_Print_Operation_RecordTo API docTo specTo body;

134.           Context     : Gtk_Print_ContextTo API docTo spec;

135.           Page_Number : GintTo API docTo spec);

136.        --  Called for every page that is printed. This handler must render the

137.        --  page Page_Number onto the cairo context obtained from Context using

138.        --  Gtk.Print_Context.Get_Cairo_Context.

139.        --

140.        --  Use Gtk.Print_Operation.Set_Use_Full_Page and

141.        --  Gtk.Print_Operation.Set_Unit before starting the print operation to set

142.        --  up the transformation of the cairo context according to your needs.

143.        --

144.        --  This is the main printing handler. This has to be overriden for the

145.        --  printing operation to work.

147.        procedure Begin_PrintTo API docTo body

148.          (Op      : access Gtkada_Print_Operation_RecordTo API docTo specTo body;

149.           Context : Gtk_Print_ContextTo API docTo spec);

150.        --  Called after the user has finished changing print settings in the

151.        --  dialog, before the actual rendering starts.

152.        --

153.        --  A typical use is to use the parameters from the

154.        --  Gtk_Print_Context and paginate the document accordingly, and then

155.        --  set the number of pages with Gtk.Print_Operation.Set_N_Pages.

157.        procedure DoneTo API docTo body

158.          (Op     : access Gtkada_Print_Operation_RecordTo API docTo specTo body;

159.           ResultTo API docTo body : Gtk_Print_Operation_ResultTo API docTo spec);

160.        --  Called when the print operation run has finished doing everything

161.        --  required for printing.

162.        --

163.        --  Result gives you information about what happened during the run.

164.        --  If Result is Result_Error then you can call Get_Error for more

165.        --  information.

166.        --

167.        --  If you enabled print status tracking then

168.        --  Gtk.Print_Operation.Is_Finished may still return False after

169.        --  done was emitted.

171.        procedure End_PrintTo API docTo body

172.          (Op      : access Gtkada_Print_Operation_RecordTo API docTo specTo body;

173.           Context : Gtk_Print_ContextTo API docTo spec);

174.        --  Called after all pages have been rendered.

175.        --

176.        --  This handler can clean up any resources that have been allocated

177.        --  in Begin_Print.

179.        function PaginateTo API docTo body

180.          (Op      : access Gtkada_Print_Operation_RecordTo API docTo specTo body;

181.           Context : Gtk_Print_ContextTo API docTo spec) return Boolean;

182.        --  Called after the "begin-print" signal, but before the actual rendering

183.        --  starts. It keeps getting called until it returns True.

184.        --

185.        --  The "paginate" signal is intended to be used for paginating a document

186.        --  in small chunks, to avoid blocking the user interface for a long

187.        --  time. This function should update the number of pages using

188.        --  Gtk.Print_Operation.Set_N_Pages, and return True if the document

189.        --  has been completely paginated.

190.        --

191.        --  If you don't need to do pagination in chunks, you can simply do

192.        --  it all in the "begin-print" handler, and set the number of pages

193.        --  from there.

195.        function PreviewTo API docTo body

196.          (Op          : access Gtkada_Print_Operation_RecordTo API docTo specTo body;

197.           Preview     : Gtk_Print_Operation_PreviewTo API docTo spec;

198.           Context     : Gtk_Print_ContextTo API docTo spec;

199.           Parent      : Gtk_WindowTo API docTo spec)

200.          return Boolean;

201.        --  Called when a preview is requested from the native dialog.

202.        --  This should return True if the in order to take over control of the

203.        --  preview.

204.        --

205.        --  The default handler for this signal uses an external viewer

206.        --  application to preview.

207.        --

208.        --  To implement a custom print preview, the overridden implementation

209.        --  should return True

210.        --  In order to use the provided Context for the preview implementation, it

211.        --  must be given a suitable cairo context with Set_Cairo_Context.

212.        --

213.        --  The custom preview implementation can use

214.        --  Gtk.Print_Operation_Preview.Is_Selected and

215.        --  Gtk.Print_Operation_Preview.Render_Page to find pages which

216.        --  are selected for print and render them. The preview must be

217.        --  finished by calling Gtk.Print_Operation_Preview.End_Preview

218.        --  (typically in response to the user clicking a close button).

220.        procedure Request_Page_SetupTo API docTo body

221.          (Op          : access Gtkada_Print_Operation_RecordTo API docTo specTo body;

222.           Context     : Gtk_Print_ContextTo API docTo spec;

223.           Page_Number : GintTo API docTo spec;

224.           Setup       : Gtk_Page_SetupTo API docTo spec);

225.        --  Called once for every page that is printed, to give the application

226.        --  a chance to modify the page setup. Any changes done to setup will be

227.        --  in force only for printing this page.

229.        procedure Status_ChangedTo API docTo body (Op : access Gtkada_Print_Operation_RecordTo API docTo specTo body);

230.        --  Called between the various phases of the print operation.

231.        --  See Gtk_Print_Status for the phases that are being discriminated.

232.        --  Use Gtk.Print_Operation.Get_Status to find out the current

233.        --  status.

235.     private

237.        type Gtkada_Print_Operation_RecordTo API docTo spec is new Gtk_Print_Operation_RecordTo API docTo specTo body with

238.          null record;

240.     end Gtkada.PrintingTo API docTo specTo body;