File: gtkada-printing.ads

-----------------------------------------------------------------------

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

--                                                                   --

--                    Copyright (C) 2010-2013, AdaCore               --

--                                                                   --

-- This library is free software; you can redistribute it and/or     --

-- modify it under the terms of the GNU General Public               --

-- License as published by the Free Software Foundation; either      --

-- version 2 of the License, or (at your option) any later version.  --

--                                                                   --

-- This library is distributed in the hope that it will be useful,   --

-- but WITHOUT ANY WARRANTY; without even the implied warranty of    --

-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU --

-- General Public License for more details.                          --

--                                                                   --

-- You should have received a copy of the GNU General Public         --

-- License along with this library; if not, write to the             --

-- Free Software Foundation, Inc., 59 Temple Place - Suite 330,      --

-- Boston, MA 02111-1307, USA.                                       --

--                                                                   --

-- As a special exception, if other files instantiate generics from  --

-- this unit, or you link this unit with other files to produce an   --

-- executable, this  unit  does not  by itself cause  the resulting  --

-- executable to be covered by the GNU General Public License. This  --

-- exception does not however invalidate any other reasons why the   --

-- executable file  might be covered by the  GNU Public License.     --

-----------------------------------------------------------------------

```
 
```
```
--  <description> 
```

--  This package provides a ready-to-use high level printing object.

--  Use functionality from Gtk.Print_Operation to manipulate the

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

--  the handlers for the printing operation.

```
-- 
```

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

--    - derive from the Gtkada_Print_Operation_Record object

--    - override the Draw_Page operation

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

```
--    - start the print operation by 
```

--          - first setting the number of pages through Set_N_Pages

--          - then calling Connect_And_Run.

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

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

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

```
-- 
```

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

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

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

```
--  </description> 
```
```
--  <example> 
```
```
-- 
```
```
--     --  Create a derived type 
```
```
-- 
```

--     type Print_Op_Record is new Gtkada_Print_Operation_Record

```
--     with record 
```
```
--        My_Data : My_Type; 
```
```
--     end record; 
```

--     type Print_Op_Access is access all Print_Op_Record'Class;

```
-- 
```
```
--     --  Override Draw_Page 
```
```
-- 
```
```
--     procedure Draw_Page 
```

--       (Print_Operation : access Print_Op_Record;

--        Context         : Gtk_Print_Context;

```
--        Page_Num        : Gint) 
```
```
--     is 
```
```
--        Cr : Cairo_Context; 
```
```
--     begin 
```

--        Cr := Get_Cairo_Context (Context);

```
-- 
```
```
--        --  Do drawing here 
```
```
-- 
```
```
--     end Draw_Page; 
```
```
-- 
```
```
-- 
```
```
--     --  Do the printing 
```
```
--     declare 
```
```
--        Print_Op : Print_Op_Access; 
```

--        Result   : Gtk_Print_Operation_Result;

```
--     begin 
```
```
--        --  Initialize 
```

--        Print_Op := new Print_Op_Record;

--        Print_Op.My_Data := Some_Data;

```
-- 
```

--        --  Set the number of pages to print

```
--        Set_N_Pages (Print_Op, 2); 
```
```
-- 
```
```
--        --  Launch the printing 
```
```
--        Result := Connect_And_Run 
```

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

```
--     end; 
```
```
-- 
```
```
--  </example> 
```
```
--  <group>Miscellaneous</group> 
```
```
 
```

with GlibTo API doc
To spec
To body; use GlibTo API doc
To spec
To body;

with Glib.ErrorTo API doc
To spec
To body;

```
 
```

with Gtk.Page_SetupTo API doc
To spec
To body;              use Gtk.Page_SetupTo API doc
To spec
To body;

with Gtk.Print_ContextTo API doc
To spec
To body;           use Gtk.Print_ContextTo API doc
To spec
To body;

with Gtk.Print_OperationTo API doc
To spec
To body;         use Gtk.Print_OperationTo API doc
To spec
To body;

with Gtk.Print_Operation_PreviewTo API doc
To spec
To body; use Gtk.Print_Operation_PreviewTo API doc
To spec
To body;

with Gtk.WindowTo API doc
To spec
To body;                  use Gtk.WindowTo API doc
To spec
To body;

```
 
```

package Gtkada.PrintingTo API doc
To spec
To body is

```
 
```

   type Gtkada_Print_Operation_RecordTo API doc
To body is new

     Gtk_Print_Operation_RecordTo API doc
To spec
To body with private;

   type Gtkada_Print_Operation is access all Gtkada_Print_Operation_RecordTo API doc
To spec
To body;

```
 
```

   procedure Gtk_NewTo API doc
To body (Op : out Gtkada_Print_OperationTo API doc
To spec);

   procedure InitializeTo API doc
To body (Widget : access Gtkada_Print_Operation_RecordTo API doc
To spec
To body'Class);

```
   --  Initialize the print operation 
```
```
 
```

   function Connect_And_RunTo API doc
To body

     (Op        : access Gtkada_Print_Operation_RecordTo API doc
To spec
To body'Class;

      ActionTo API doc
To body    : Gtk_Print_Operation_ActionTo API doc
To spec;

      Parent    : access Gtk_Window_RecordTo API doc
To spec
To body'Class;

      Error     : Glib.Error.GErrorTo API doc
To spec := null)

      return Gtk_Print_Operation_ResultTo API doc
To spec;

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

```
   --  See Gtk.Print_Operations.Run. 
```
```
 
```
```
   ------------------------- 
```
```
   -- Printing operations -- 
```
```
   ------------------------- 
```
```
 
```

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

   --  By default, these operations do nothing.

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

```
 
```

   procedure Draw_PageTo API doc
To body

     (Op          : access Gtkada_Print_Operation_RecordTo API doc
To spec
To body;

      Context     : Gtk_Print_ContextTo API doc
To spec;

      Page_Number : GintTo API doc
To spec);

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

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

   --  Gtk.Print_Context.Get_Cairo_Context.

```
   -- 
```

   --  Use Gtk.Print_Operation.Set_Use_Full_Page and

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

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

```
   -- 
```

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

```
   --  printing operation to work. 
```
```
 
```

   procedure Begin_PrintTo API doc
To body

     (Op      : access Gtkada_Print_Operation_RecordTo API doc
To spec
To body;

      Context : Gtk_Print_ContextTo API doc
To spec);

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

   --  dialog, before the actual rendering starts.

```
   -- 
```

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

   --  Gtk_Print_Context and paginate the document accordingly, and then

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

```
 
```
```
   procedure DoneTo API doc
To body 
```

     (Op     : access Gtkada_Print_Operation_RecordTo API doc
To spec
To body;

      ResultTo API doc
To body : Gtk_Print_Operation_ResultTo API doc
To spec);

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

```
   --  required for printing. 
```
```
   -- 
```

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

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

```
   --  information. 
```
```
   -- 
```

   --  If you enabled print status tracking then

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

```
   --  done was emitted. 
```
```
 
```

   procedure End_PrintTo API doc
To body

     (Op      : access Gtkada_Print_Operation_RecordTo API doc
To spec
To body;

      Context : Gtk_Print_ContextTo API doc
To spec);

   --  Called after all pages have been rendered.

```
   -- 
```

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

```
   --  in Begin_Print. 
```
```
 
```
```
   function PaginateTo API doc
To body 
```

     (Op      : access Gtkada_Print_Operation_RecordTo API doc
To spec
To body;

      Context : Gtk_Print_ContextTo API doc
To spec) return Boolean;

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

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

```
   -- 
```

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

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

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

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

```
   --  has been completely paginated. 
```
```
   -- 
```

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

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

```
   --  from there. 
```
```
 
```
```
   function PreviewTo API doc
To body 
```

     (Op          : access Gtkada_Print_Operation_RecordTo API doc
To spec
To body;

      Preview     : Gtk_Print_Operation_PreviewTo API doc
To spec;

      Context     : Gtk_Print_ContextTo API doc
To spec;

      Parent      : Gtk_WindowTo API doc
To spec)

```
     return Boolean; 
```

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

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

```
   --  preview. 
```
```
   -- 
```

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

```
   --  application to preview. 
```
```
   -- 
```

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

```
   --  should return True 
```

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

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

```
   -- 
```

   --  The custom preview implementation can use

   --  Gtk.Print_Operation_Preview.Is_Selected and

   --  Gtk.Print_Operation_Preview.Render_Page to find pages which

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

   --  finished by calling Gtk.Print_Operation_Preview.End_Preview

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

```
 
```

   procedure Request_Page_SetupTo API doc
To body

     (Op          : access Gtkada_Print_Operation_RecordTo API doc
To spec
To body;

      Context     : Gtk_Print_ContextTo API doc
To spec;

      Page_Number : GintTo API doc
To spec;

      Setup       : Gtk_Page_SetupTo API doc
To spec);

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

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

   --  in force only for printing this page.

```
 
```

   procedure Status_ChangedTo API doc
To body (Op : access Gtkada_Print_Operation_RecordTo API doc
To spec
To body);

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

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

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

```
   --  status. 
```
```
 
```
```
private 
```
```
 
```

   type Gtkada_Print_Operation_RecordTo API doc
To spec is new Gtk_Print_Operation_RecordTo API doc
To spec
To body with

```
     null record; 
```
```
 
```

end Gtkada.PrintingTo API doc
To spec
To body;

Documentation