1. ----------------------------------------------------------------------- 
  2. --               GtkAda - Ada95 binding for Gtk+/Gnome               -- 
  3. --                                                                   -- 
  4. --                    Copyright (C) 2010-2013, 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. ----------------------------------------------------------------------- 
  28.  
  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> 
  54.  
  55. with Glib.Error; 
  56. with Glib.Object; 
  57. with Glib.Properties; 
  58. with Gtk.Enums; 
  59. with Gtk.Page_Setup; 
  60. with Gtk.Print_Settings; 
  61. with Gtk.Window; 
  62.  
  63. package Gtk.Print_Operation is 
  64.  
  65.    type Gtk_Print_Operation_Record is 
  66.      new Glib.Object.GObject_Record with private; 
  67.    type Gtk_Print_Operation is access all Gtk_Print_Operation_Record'Class; 
  68.  
  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_Status); 
  80.  
  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_Result); 
  87.  
  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_Action); 
  94.  
  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_Error); 
  101.  
  102.    procedure Gtk_New (Widget : out Gtk_Print_Operation); 
  103.    procedure Initialize (Widget : access Gtk_Print_Operation_Record'Class); 
  104.    --  Creates a new Gtk_Print_Operation. 
  105.  
  106.    function Get_Type return GType; 
  107.  
  108.    function Error_Quark return GQuark; 
  109.    --  Registers an error quark for Gtk_Print_Operation if necessary. 
  110.  
  111.    function Run 
  112.      (Op     : access Gtk_Print_Operation_Record; 
  113.       Action : Gtk_Print_Operation_Action; 
  114.       Parent : access Gtk.Window.Gtk_Window_Record'Class; 
  115.       Error  : Glib.Error.GError := null) 
  116.       return Gtk_Print_Operation_Result; 
  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. 
  179.  
  180.    procedure Cancel (Op : access Gtk_Print_Operation_Record); 
  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. 
  184.  
  185.    procedure Draw_Page_Finish (Op : access Gtk_Print_Operation_Record); 
  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. 
  192.  
  193.    procedure Get_Error 
  194.      (Op    : access Gtk_Print_Operation_Record; 
  195.       Error : Glib.Error.GError); 
  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. 
  199.  
  200.    function Get_Print_Settings 
  201.      (Op : access Gtk_Print_Operation_Record) 
  202.       return Gtk.Print_Settings.Gtk_Print_Settings; 
  203.    procedure Set_Print_Settings 
  204.      (Op             : access Gtk_Print_Operation_Record; 
  205.       Print_Settings : access 
  206.                        Gtk.Print_Settings.Gtk_Print_Settings_Record'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. 
  212.  
  213.    function Get_Status 
  214.      (Op : access Gtk_Print_Operation_Record) return Gtk_Print_Status; 
  215.    function Get_Status (Op : access Gtk_Print_Operation_Record) 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. 
  223.  
  224.    function Is_Finished 
  225.      (Op : access Gtk_Print_Operation_Record) 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. 
  233.  
  234.    procedure Set_Allow_Async 
  235.      (Op          : access Gtk_Print_Operation_Record; 
  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. 
  239.  
  240.    procedure Set_Current_Page 
  241.      (Op           : access Gtk_Print_Operation_Record; 
  242.       Current_Page : Gint); 
  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. 
  249.  
  250.    procedure Set_Custom_Tab_Label 
  251.      (Op    : access Gtk_Print_Operation_Record; 
  252.       Label : String); 
  253.    --  Sets the label for the tab holding custom widgets. 
  254.  
  255.    procedure Set_Defer_Drawing (Op : access Gtk_Print_Operation_Record); 
  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. 
  260.  
  261.    procedure Set_Export_Filename 
  262.      (Op       : access Gtk_Print_Operation_Record; 
  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. 
  272.  
  273.    procedure Set_Job_Name 
  274.      (Op       : access Gtk_Print_Operation_Record; 
  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. 
  281.  
  282.    procedure Set_N_Pages 
  283.      (Op      : access Gtk_Print_Operation_Record; 
  284.       N_Pages : Gint); 
  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. 
  293.  
  294.    procedure Set_Show_Progress 
  295.      (Op            : access Gtk_Print_Operation_Record; 
  296.       Show_Progress : Boolean); 
  297.    --  If True, the print operation will show a progress dialog during the 
  298.    --  print operation. 
  299.  
  300.    procedure Set_Track_Print_Status 
  301.      (Op           : access Gtk_Print_Operation_Record; 
  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. 
  310.  
  311.    procedure Set_Unit 
  312.      (Op   : access Gtk_Print_Operation_Record; 
  313.       Unit : Gtk.Enums.Gtk_Unit); 
  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. 
  317.  
  318.    procedure Set_Use_Full_Page 
  319.      (Op        : access Gtk_Print_Operation_Record; 
  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). 
  327.  
  328.    ---------------- 
  329.    -- Page Setup -- 
  330.    ---------------- 
  331.  
  332.    function Get_Default_Page_Setup 
  333.      (Op : access Gtk_Print_Operation_Record) 
  334.       return Gtk.Page_Setup.Gtk_Page_Setup; 
  335.    procedure Set_Default_Page_Setup 
  336.      (Op                 : access Gtk_Print_Operation_Record; 
  337.       Default_Page_Setup : access Gtk.Page_Setup.Gtk_Page_Setup_Record'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. 
  343.  
  344.    function Run_Page_Setup_Dialog 
  345.      (Parent     : access Gtk.Window.Gtk_Window_Record'Class; 
  346.       Page_Setup : access Gtk.Page_Setup.Gtk_Page_Setup_Record'Class; 
  347.       Settings   : access Gtk.Print_Settings.Gtk_Print_Settings_Record'Class) 
  348.       return Gtk.Page_Setup.Gtk_Page_Setup; 
  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. 
  356.  
  357.    ---------------- 
  358.    -- Properties -- 
  359.    ---------------- 
  360.  
  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> 
  422.  
  423.    Allow_Async_Property        : constant Glib.Properties.Property_Boolean; 
  424.    Current_Page_Property       : constant Glib.Properties.Property_Int; 
  425.    Custom_Tab_Label_Property   : constant Glib.Properties.Property_String; 
  426.    Default_Page_Setup_Property : constant Glib.Properties.Property_Object; 
  427.    Export_Filename_Property    : constant Glib.Properties.Property_String; 
  428.    Job_Name_Property           : constant Glib.Properties.Property_String; 
  429.    N_Pages_Property            : constant Glib.Properties.Property_Int; 
  430.    Print_Settings_Property     : constant Glib.Properties.Property_Object; 
  431.    Show_Progress_Property      : constant Glib.Properties.Property_Boolean; 
  432.    Status_Property             : constant Glib.Properties.Property_Enum; 
  433.    Status_String_Property      : constant Glib.Properties.Property_String; 
  434.    Track_Print_Status_Property : constant Glib.Properties.Property_Boolean; 
  435.    Unit_Property               : constant Glib.Properties.Property_Enum; 
  436.    Use_Full_Page_Property      : constant Glib.Properties.Property_Boolean; 
  437.  
  438. private 
  439.  
  440.    type Gtk_Print_Operation_Record is 
  441.      new Glib.Object.GObject_Record with null record; 
  442.  
  443.    Allow_Async_Property : constant Glib.Properties.Property_Boolean := 
  444.      Glib.Properties.Build ("allow-async"); 
  445.    Current_Page_Property : constant Glib.Properties.Property_Int := 
  446.      Glib.Properties.Build ("current-page"); 
  447.    Custom_Tab_Label_Property : constant Glib.Properties.Property_String := 
  448.      Glib.Properties.Build ("custom-tab-label"); 
  449.    Default_Page_Setup_Property : constant Glib.Properties.Property_Object := 
  450.      Glib.Properties.Build ("default-page-setup"); 
  451.    Export_Filename_Property : constant Glib.Properties.Property_String := 
  452.      Glib.Properties.Build ("export-filename"); 
  453.    Job_Name_Property : constant Glib.Properties.Property_String := 
  454.      Glib.Properties.Build ("job-name"); 
  455.    N_Pages_Property : constant Glib.Properties.Property_Int := 
  456.      Glib.Properties.Build ("n-pages"); 
  457.    Print_Settings_Property : constant Glib.Properties.Property_Object := 
  458.      Glib.Properties.Build ("print-settings"); 
  459.    Show_Progress_Property : constant Glib.Properties.Property_Boolean := 
  460.      Glib.Properties.Build ("show-progress"); 
  461.    Status_Property : constant Glib.Properties.Property_Enum := 
  462.      Glib.Properties.Build ("status"); 
  463.    Status_String_Property : constant Glib.Properties.Property_String := 
  464.      Glib.Properties.Build ("status-string"); 
  465.    Track_Print_Status_Property : constant Glib.Properties.Property_Boolean := 
  466.      Glib.Properties.Build ("track-print-status"); 
  467.    Unit_Property : constant Glib.Properties.Property_Enum := 
  468.      Glib.Properties.Build ("unit"); 
  469.    Use_Full_Page_Property : constant Glib.Properties.Property_Boolean := 
  470.      Glib.Properties.Build ("use-full-page"); 
  471.  
  472.    pragma Import (C, Get_Type, "gtk_print_operation_get_type"); 
  473.    pragma Import (C, Error_Quark, "gtk_print_error_quark"); 
  474.  
  475. end Gtk.Print_Operation;