## 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.     --  Gtk_Print_Operation is the high-level, portable printing API. It looks a

31.     --  bit different than other GTK+ dialogs such as the Gtk_File_Chooser, since

32.     --  some platforms don't expose enough infrastructure to implement a good print

33.     --  dialog. On such platforms, Gtk_Print_Operation uses the native print

34.     --  dialog. On platforms which do not provide a native print dialog, GTK+ uses

35.     --  its own, see Gtk_Print_Unix_Dialog.

36.     --

37.     --  The typical way to use the high-level printing API is to create a

38.     --  Gtk_Print_Operation object with Gtk_New when the user selects to print.

39.     --  Then you set some properties on it, e.g. the page size, any

40.     --  Gtk_Print_Settings from previous print operations, the number of pages,

41.     --  the current page, etc.

42.     --

43.     --  Then you start the print operation by calling Run. It will then show a

44.     --  dialog, let the user select a printer and options. When the user finished

45.     --  the dialog various signals will be emitted on the Gtk_Print_Operation, the

46.     --  main one being draw-page, which you are supposed to catch and render the

47.     --  page on the provided Gtk_Print_Context using Cairo.

48.     --

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

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

51.     --  to the root directory of your Gtk+ install before calling Run.

52.     --  </description>

53.     --  <c_version>2.16.6</c_version>

55.     with Glib.ErrorTo API docTo specTo body;

56.     with Glib.ObjectTo API docTo specTo body;

57.     with Glib.PropertiesTo API docTo specTo body;

58.     with Gtk.EnumsTo API docTo specTo body;

59.     with Gtk.Page_SetupTo API docTo specTo body;

60.     with Gtk.Print_SettingsTo API docTo specTo body;

61.     with Gtk.WindowTo API docTo specTo body;

63.     package Gtk.Print_OperationTo API docTo specTo body is

65.        type Gtk_Print_Operation_RecordTo API docTo body is

66.          new Glib.Object.GObject_RecordTo API docTo specTo body with private;

67.        type Gtk_Print_Operation is access all Gtk_Print_Operation_RecordTo API docTo specTo body'Class;

69.        type Gtk_Print_Status is

70.          (Status_Initial,

71.           Status_Preparing,

72.           Status_Generating_Data,

73.           Status_Sending_Data,

74.           Status_Pending,

75.           Status_Pending_Issue,

76.           Status_Printing,

77.           Status_Finished,

78.           Status_Finished_Aborted);

79.        pragma Convention (C, Gtk_Print_StatusTo API docTo spec);

81.        type Gtk_Print_Operation_Result is

82.          (Result_Error,

83.           Result_Apply,

84.           Result_Cancel,

85.           Result_In_Progress);

86.        pragma Convention (C, Gtk_Print_Operation_ResultTo API docTo spec);

88.        type Gtk_Print_Operation_Action is

89.          (Action_Print_Dialog,

90.           Action_Print,

91.           Action_Preview,

92.           Action_Export);

93.        pragma Convention (C, Gtk_Print_Operation_ActionTo API docTo spec);

95.        type Gtk_Print_Error is

96.          (Error_General,

97.           Error_Internal_Error,

98.           Error_Nomem,

99.           Error_Invalid_File);

100.        pragma Convention (C, Gtk_Print_ErrorTo API docTo spec);

102.        procedure Gtk_NewTo API docTo body (Widget : out Gtk_Print_OperationTo API docTo spec);

103.        procedure InitializeTo API docTo body (Widget : access Gtk_Print_Operation_RecordTo API docTo specTo body'Class);

104.        --  Creates a new Gtk_Print_Operation.

106.        function Get_TypeTo API docTo body return GTypeTo API docTo spec;

108.        function Error_QuarkTo API docTo body return GQuarkTo API docTo spec;

109.        --  Registers an error quark for Gtk_Print_Operation if necessary.

111.        function RunTo API docTo body

112.          (Op     : access Gtk_Print_Operation_RecordTo API docTo specTo body;

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

114.           Parent : access Gtk.Window.Gtk_Window_RecordTo API docTo specTo body'Class;

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

116.           return Gtk_Print_Operation_ResultTo API docTo spec;

117.        --  Runs the print operation, by first letting the user modify

118.        --  print settings in the print dialog, and then by printing the

119.        --  document.

120.        --

121.        --  Normally that this function does not return until the rendering of all

122.        --  pages is complete. You can connect to the status-changed signal on Op

123.        --  to obtain some information about the progress of the print operation.

124.        --  Furthermore, it may use a recursive mainloop to show the print dialog.

125.        --

126.        --  If you call Set_Allow_Async or set the allow-async property the

127.        --  operation will run asynchronously if this is supported on the platform.

128.        --  The done signal will be emitted with the result of the operation when

129.        --  it is done (i.e. when the dialog is canceled, or when the print succeeds

130.        --  or fails).

131.        --

132.        --     begin

133.        --        if Settings /= null then

134.        --           Set_Print_Settings (Print, Settings);

135.        --        end if;

136.        --

137.        --        if Page_Setup /= null then

138.        --           Set_Default_Page_Setup (Print, Page_Setup);

139.        --        end if;

140.        --

141.        --        Connect (Print, "begin-print", Begin_Print'Access, User_Data);

142.        --        Connect (Print, "draw-page",   Draw_Page'Access,   User_Data);

143.        --

144.        --        Result := Run (Print, Action_Print_Dialog, Parent, Error);

145.        --

146.        --        case Result is

147.        --           when Result_Error =>

148.        --              Gtk_New

149.        --                (Error_Dialog,

150.        --                 Parent,

151.        --                 Destroy_With_Parent,

152.        --                 Message_Error,

153.        --                 Buttons_Close,

154.        --                 "Error printing file");

155.        --              Connect

156.        --                (Error_Dialog, "response", Gtk_Widget_Destroy'Access);

157.        --              Show (Error_Dialog);

158.        --              Glib.Error.Error_Free (Error);

159.        --

160.        --           when Result_Apply =>

161.        --              if Settings /= null then

162.        --                 Unref (Settings);

163.        --              end if;

164.        --              Settings := Get_Print_Settings (Print);

165.        --              Ref (Settings);

166.        --

167.        --           when Result_Cancel =>      null;

168.        --           when Result_In_Progress => null;

169.        --        end case;

170.        --

171.        --  Note that Run can only be called once on a given Gtk_Print_Operation.

172.        --

173.        --  Return value: the result of the print operation. A return value of

174.        --  Result_Apply indicates that the printing was completed successfully.

175.        --  In this case, it is a good idea to obtain the used print settings with

176.        --  Get_Print_Settings and store them for reuse with the next print

177.        --  operation. A value of Result_In_Progress means the operation is running

178.        --  asynchronously, and will emit the done signal when done.

180.        procedure CancelTo API docTo body (Op : access Gtk_Print_Operation_RecordTo API docTo specTo body);

181.        --  Cancels a running print operation. This function may be called from

182.        --  a begin-print, paginate or draw-page signal handler to stop the

183.        --  currently running print operation.

185.        procedure Draw_Page_FinishTo API docTo body (Op : access Gtk_Print_Operation_RecordTo API docTo specTo body);

186.        --  Signal that drawing of particular page is complete.

187.        --

188.        --  It is called after completion of page drawing (e.g. drawing in another

189.        --  thread).  If Set_Defer_Drawing was called before, then this function has

190.        --  to be called by application. In another case it is called by the library

191.        --  itself.

193.        procedure Get_ErrorTo API docTo body

194.          (Op    : access Gtk_Print_Operation_RecordTo API docTo specTo body;

195.           Error : Glib.Error.GErrorTo API docTo spec);

196.        --  Call this when the result of a print operation is

197.        --  Result_Error, either as returned by Run, or in the done signal handler.

198.        --  The returned GError will contain more details on what went wrong.

200.        function Get_Print_SettingsTo API docTo body

201.          (Op : access Gtk_Print_Operation_RecordTo API docTo specTo body)

202.           return Gtk.Print_Settings.Gtk_Print_SettingsTo API docTo spec;

203.        procedure Set_Print_SettingsTo API docTo body

204.          (Op             : access Gtk_Print_Operation_RecordTo API docTo specTo body;

205.           Print_Settings : access

206.                            Gtk.Print_Settings.Gtk_Print_Settings_RecordTo API docTo specTo body'Class);

207.        --  Manipulate the print settings for Op. This is typically used to

208.        --  re-establish print settings from a previous print operation, see Run.

209.        --

210.        --  Note that the Get_Print_Setting's return value is null until either

211.        --  Set_Print_Settings or Run have been called.

213.        function Get_StatusTo API docTo body

214.          (Op : access Gtk_Print_Operation_RecordTo API docTo specTo body) return Gtk_Print_StatusTo API docTo spec;

215.        function Get_StatusTo API docTo body (Op : access Gtk_Print_Operation_RecordTo API docTo specTo body) return String;

216.        --  Returns the status of the print operation.

217.        --

218.        --  A Gtk_Print_Status is suitable for programmatic use.

219.        --

220.        --  The String returned is a translated string representation of the

221.        --  status of the print operation.  It is suitable for displaying the

222.        --  print status in, e.g., a Gtk_Statusbar.

224.        function Is_FinishedTo API docTo body

225.          (Op : access Gtk_Print_Operation_RecordTo API docTo specTo body) return Boolean;

226.        --  A convenience function to find out whether the print operation

227.        --  is finished, either successfully (Status_Finished) or unsuccessfully

228.        --  (Status_Finished_Aborted).

229.        --

230.        --  Note: when you enable print status tracking the print operation

231.        --  can be in a non-finished state even after done has been called, as

232.        --  the operation status then tracks the print job status on the printer.

234.        procedure Set_Allow_AsyncTo API docTo body

235.          (Op          : access Gtk_Print_Operation_RecordTo API docTo specTo body;

236.           Allow_Async : Boolean);

237.        --  Sets whether Run may return before the print operation is completed.

238.        --  Note that some platforms may not allow asynchronous operation.

240.        procedure Set_Current_PageTo API docTo body

241.          (Op           : access Gtk_Print_Operation_RecordTo API docTo specTo body;

242.           Current_Page : GintTo API docTo spec);

243.        --  Sets the current page.

244.        --

245.        --  If this is called before Run, the user will be able to select to print

246.        --  only the current page.

247.        --

248.        --  Note that this only makes sense for pre-paginated documents.

250.        procedure Set_Custom_Tab_LabelTo API docTo body

251.          (Op    : access Gtk_Print_Operation_RecordTo API docTo specTo body;

252.           Label : String);

253.        --  Sets the label for the tab holding custom widgets.

255.        procedure Set_Defer_DrawingTo API docTo body (Op : access Gtk_Print_Operation_RecordTo API docTo specTo body);

256.        --  Sets up the Gtk_Print_Operation to wait for calling of Draw_Page_Finish

257.        --  from application. It can be used for drawing page in another thread.

258.        --

259.        --  This function must be called in the callback of "draw-page" signal.

261.        procedure Set_Export_FilenameTo API docTo body

262.          (Op       : access Gtk_Print_Operation_RecordTo API docTo specTo body;

263.           Filename : String);

264.        --  Sets up the Gtk_Print_Operation to generate a file instead

265.        --  of showing the print dialog. The indended use of this function

266.        --  is for implementing "Export to PDF" actions. Currently, PDF

267.        --  is the only supported format.

268.        --

269.        --  "Print to PDF" support is independent of this and is done

270.        --  by letting the user pick the "Print to PDF" item from the list

271.        --  of printers in the print dialog.

273.        procedure Set_Job_NameTo API docTo body

274.          (Op       : access Gtk_Print_Operation_RecordTo API docTo specTo body;

275.           Job_Name : String);

276.        --  Sets the name of the print job. The name is used to identify

277.        --  the job (e.g. in monitoring applications like eggcups).

278.        --

279.        --  If you don't set a job name, GTK+ picks a default one by

280.        --  numbering successive print jobs.

282.        procedure Set_N_PagesTo API docTo body

283.          (Op      : access Gtk_Print_Operation_RecordTo API docTo specTo body;

284.           N_Pages : GintTo API docTo spec);

285.        --  Sets the number of pages in the document.

286.        --

287.        --  This MUST be set to a positive number before the rendering starts.

288.        --  It may be set in a begin-print signal hander.

289.        --

290.        --  Note that the page numbers passed to the request-page-setup and

291.        --  draw-page signals are 0-based, i.e. if the user chooses to print all

292.        --  pages, the last draw-page signal will be for page N_Pages - 1.

294.        procedure Set_Show_ProgressTo API docTo body

295.          (Op            : access Gtk_Print_Operation_RecordTo API docTo specTo body;

296.           Show_Progress : Boolean);

297.        --  If True, the print operation will show a progress dialog during the

298.        --  print operation.

300.        procedure Set_Track_Print_StatusTo API docTo body

301.          (Op           : access Gtk_Print_Operation_RecordTo API docTo specTo body;

302.           Track_Status : Boolean);

303.        --  If True, the print operation will try to continue report on the status

304.        --  of the print job in the printer queues and printer. This can allow your

305.        --  application to show things like "out of paper" issues, and when the

306.        --  print job actually reaches the printer.

307.        --

308.        --  This function is often implemented using some form of polling, so it

309.        --  should not be enabled unless needed.

311.        procedure Set_UnitTo API docTo body

312.          (Op   : access Gtk_Print_Operation_RecordTo API docTo specTo body;

313.           UnitTo API docTo body : Gtk.Enums.Gtk_UnitTo API docTo spec);

314.        --  Sets up the transformation for the cairo context obtained from

315.        --  Gtk_Print_Context in such a way that distances are measured in

316.        --  units of Unit.

318.        procedure Set_Use_Full_PageTo API docTo body

319.          (Op        : access Gtk_Print_Operation_RecordTo API docTo specTo body;

320.           Full_Page : Boolean);

321.        --  If True, the transformation for the cairo context obtained from

322.        --  Gtk_Print_Context puts the origin at the top left corner of the page

323.        --  (which may not be the top left corner of the sheet, depending on page

324.        --  orientation and the number of pages per sheet). Otherwise, the origin

325.        --  is at the top left corner of the imageable area (i.e. inside the

326.        --  margins).

328.        ----------------

329.        -- Page Setup --

330.        ----------------

332.        function Get_Default_Page_SetupTo API docTo body

333.          (Op : access Gtk_Print_Operation_RecordTo API docTo specTo body)

334.           return Gtk.Page_Setup.Gtk_Page_SetupTo API docTo spec;

335.        procedure Set_Default_Page_SetupTo API docTo body

336.          (Op                 : access Gtk_Print_Operation_RecordTo API docTo specTo body;

337.           Default_Page_Setup : access Gtk.Page_Setup.Gtk_Page_Setup_RecordTo API docTo specTo body'Class);

338.        --  Makes Default_Page_Setup the default page setup for Op.

339.        --  Default_Page_Setup may be null.

340.        --

341.        --  This page setup will be used by Run, but it can be overridden on a

342.        --  per-page basis by connecting to the request-page-setup signal.

344.        function Run_Page_Setup_DialogTo API docTo body

345.          (Parent     : access Gtk.Window.Gtk_Window_RecordTo API docTo specTo body'Class;

346.           Page_Setup : access Gtk.Page_Setup.Gtk_Page_Setup_RecordTo API docTo specTo body'Class;

347.           Settings   : access Gtk.Print_Settings.Gtk_Print_Settings_RecordTo API docTo specTo body'Class)

348.           return Gtk.Page_Setup.Gtk_Page_SetupTo API docTo spec;

349.        --  Runs a page setup dialog, letting the user modify the values from

350.        --  Page_Setup. If the user cancels the dialog, the returned Gtk_Page_Setup

351.        --  is identical to the passed in Page_Setup, otherwise it contains the

352.        --  modifications done in the dialog.

353.        --

354.        --  Note that this function may use a recursive mainloop to show the page

355.        --  setup dialog.

357.        ----------------

358.        -- Properties --

359.        ----------------

361.        --  <properties>

362.        --  Name:  Allow_Async_Property

363.        --  Type:  Boolean

364.        --  Descr: True if print process may run asynchronous.

365.        --

366.        --  Name:  Current_Page_Property

367.        --  Type:  Int

368.        --  Descr: The current page in the document

369.        --

370.        --  Name:  Custom_Tab_Label_Property

371.        --  Type:  String

372.        --  Descr: Label for the tab containing custom widgets.

373.        --

374.        --  Name:  Default_Page_Setup_Property

375.        --  Type:  Object

376.        --  Descr: The Gtk_Page_Setup used by default

377.        --

378.        --  Name:  Export_Filename_Property

379.        --  Type:  String

380.        --  Descr: Export filename

381.        --

382.        --  Name:  Job_Name_Property

383.        --  Type:  String

384.        --  Descr: A string used for identifying the print job.

385.        --

386.        --  Name:  N_Pages_Property

387.        --  Type:  Int

388.        --  Descr: The number of pages in the document.

389.        --

390.        --  Name:  Print_Settings_Property

391.        --  Type:  Object

392.        --  Descr: The Gtk_Print_Settings used for initializing the dialog

393.        --

394.        --  Name:  Show_Progress_Property

395.        --  Type:  Boolean

396.        --  Descr: True if a progress dialog is shown while printing.

397.        --

398.        --  Name:  Status_Property

399.        --  Type:  Enum

400.        --  Descr: The status of the print operation

401.        --

402.        --  Name:  Status_String_Property

403.        --  Type:  String

404.        --  Descr: A human-readable description of the status

405.        --

406.        --  Name:  Track_Print_Status_Property

407.        --  Type:  Boolean

408.        --  Descr: True if the print operation will continue to report on the

409.        --         print job status after the print data has been sent to the

410.        --         printer or print server.

411.        --

412.        --  Name:  Unit_Property

413.        --  Type:  Enum

414.        --  Descr: The unit in which distances can be measured in the context

415.        --

416.        --  Name:  Use_Full_Page_Property

417.        --  Type:  Boolean

418.        --  Descr: True if the origin of the context should be at the corner of

419.        --         the page and not the corner of the imageable area

420.        --

421.        --  </properties>

423.        Allow_Async_Property        : constant Glib.Properties.Property_BooleanTo API docTo spec;

424.        Current_Page_Property       : constant Glib.Properties.Property_IntTo API docTo spec;

425.        Custom_Tab_Label_Property   : constant Glib.Properties.Property_StringTo API docTo spec;

426.        Default_Page_Setup_Property : constant Glib.Properties.Property_ObjectTo API docTo spec;

427.        Export_Filename_Property    : constant Glib.Properties.Property_StringTo API docTo spec;

428.        Job_Name_Property           : constant Glib.Properties.Property_StringTo API docTo spec;

429.        N_Pages_Property            : constant Glib.Properties.Property_IntTo API docTo spec;

430.        Print_Settings_Property     : constant Glib.Properties.Property_ObjectTo API docTo spec;

431.        Show_Progress_Property      : constant Glib.Properties.Property_BooleanTo API docTo spec;

432.        Status_Property             : constant Glib.Properties.Property_EnumTo API docTo spec;

433.        Status_String_Property      : constant Glib.Properties.Property_StringTo API docTo spec;

434.        Track_Print_Status_Property : constant Glib.Properties.Property_BooleanTo API docTo spec;

435.        Unit_Property               : constant Glib.Properties.Property_EnumTo API docTo spec;

436.        Use_Full_Page_Property      : constant Glib.Properties.Property_BooleanTo API docTo spec;

438.     private

440.        type Gtk_Print_Operation_RecordTo API docTo spec is

441.          new Glib.Object.GObject_RecordTo API docTo specTo body with null record;

443.        Allow_Async_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

444.          Glib.Properties.BuildTo API docTo specTo body ("allow-async");

445.        Current_Page_PropertyTo API docTo spec : constant Glib.Properties.Property_IntTo API docTo spec :=

446.          Glib.Properties.BuildTo API docTo specTo body ("current-page");

447.        Custom_Tab_Label_PropertyTo API docTo spec : constant Glib.Properties.Property_StringTo API docTo spec :=

448.          Glib.Properties.BuildTo API docTo specTo body ("custom-tab-label");

449.        Default_Page_Setup_PropertyTo API docTo spec : constant Glib.Properties.Property_ObjectTo API docTo spec :=

450.          Glib.Properties.BuildTo API docTo specTo body ("default-page-setup");

451.        Export_Filename_PropertyTo API docTo spec : constant Glib.Properties.Property_StringTo API docTo spec :=

452.          Glib.Properties.BuildTo API docTo specTo body ("export-filename");

453.        Job_Name_PropertyTo API docTo spec : constant Glib.Properties.Property_StringTo API docTo spec :=

454.          Glib.Properties.BuildTo API docTo specTo body ("job-name");

455.        N_Pages_PropertyTo API docTo spec : constant Glib.Properties.Property_IntTo API docTo spec :=

456.          Glib.Properties.BuildTo API docTo specTo body ("n-pages");

457.        Print_Settings_PropertyTo API docTo spec : constant Glib.Properties.Property_ObjectTo API docTo spec :=

458.          Glib.Properties.BuildTo API docTo specTo body ("print-settings");

459.        Show_Progress_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

460.          Glib.Properties.BuildTo API docTo specTo body ("show-progress");

461.        Status_PropertyTo API docTo spec : constant Glib.Properties.Property_EnumTo API docTo spec :=

462.          Glib.Properties.BuildTo API docTo specTo body ("status");

463.        Status_String_PropertyTo API docTo spec : constant Glib.Properties.Property_StringTo API docTo spec :=

464.          Glib.Properties.BuildTo API docTo specTo body ("status-string");

465.        Track_Print_Status_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

466.          Glib.Properties.BuildTo API docTo specTo body ("track-print-status");

467.        Unit_PropertyTo API docTo spec : constant Glib.Properties.Property_EnumTo API docTo spec :=

468.          Glib.Properties.BuildTo API docTo specTo body ("unit");

469.        Use_Full_Page_PropertyTo API docTo spec : constant Glib.Properties.Property_BooleanTo API docTo spec :=

470.          Glib.Properties.BuildTo API docTo specTo body ("use-full-page");

472.        pragma Import (C, Get_TypeTo API docTo spec, "gtk_print_operation_get_type");

473.        pragma Import (C, Error_QuarkTo API docTo spec, "gtk_print_error_quark");

475.     end Gtk.Print_OperationTo API docTo specTo body;