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. -- -- -- -- -- -- -- -- -- -- -- --
  22. ----------------------------------------------------------------------- 
  23.  
  24. --  <description> 
  25. --  Gtk_Print_Operation is the high-level, portable printing API. It looks a 
  26. --  bit different than other GTK+ dialogs such as the Gtk_File_Chooser, since 
  27. --  some platforms don't expose enough infrastructure to implement a good print 
  28. --  dialog. On such platforms, Gtk_Print_Operation uses the native print 
  29. --  dialog. On platforms which do not provide a native print dialog, GTK+ uses 
  30. --  its own, see Gtk_Print_Unix_Dialog. 
  31. -- 
  32. --  The typical way to use the high-level printing API is to create a 
  33. --  Gtk_Print_Operation object with Gtk_New when the user selects to print. 
  34. --  Then you set some properties on it, e.g. the page size, any 
  35. --  Gtk_Print_Settings from previous print operations, the number of pages, 
  36. --  the current page, etc. 
  37. -- 
  38. --  Then you start the print operation by calling Run. It will then show a 
  39. --  dialog, let the user select a printer and options. When the user finished 
  40. --  the dialog various signals will be emitted on the Gtk_Print_Operation, the 
  41. --  main one being draw-page, which you are supposed to catch and render the 
  42. --  page on the provided Gtk_Print_Context using Cairo. 
  43. -- 
  44. --  Note: on UNIX/Linux, Gtk+ is loading at run-time the libraries for printing 
  45. --  support. You will need to point the environment variable GTK_EXE_PREFIX 
  46. --  to the root directory of your Gtk+ install before calling Run. 
  47. --  </description> 
  48. --  <c_version>2.16.6</c_version> 
  49.  
  50. with Glib.Error; 
  51. with Glib.Object; 
  52. with Glib.Properties; 
  53. with Gtk.Enums; 
  54. with Gtk.Page_Setup; 
  55. with Gtk.Print_Settings; 
  56. with Gtk.Window; 
  57.  
  58. package Gtk.Print_Operation is 
  59.  
  60.    type Gtk_Print_Operation_Record is 
  61.      new Glib.Object.GObject_Record with private; 
  62.    type Gtk_Print_Operation is access all Gtk_Print_Operation_Record'Class; 
  63.  
  64.    type Gtk_Print_Status is 
  65.      (Status_Initial, 
  66.       Status_Preparing, 
  67.       Status_Generating_Data, 
  68.       Status_Sending_Data, 
  69.       Status_Pending, 
  70.       Status_Pending_Issue, 
  71.       Status_Printing, 
  72.       Status_Finished, 
  73.       Status_Finished_Aborted); 
  74.    pragma Convention (C, Gtk_Print_Status); 
  75.  
  76.    type Gtk_Print_Operation_Result is 
  77.      (Result_Error, 
  78.       Result_Apply, 
  79.       Result_Cancel, 
  80.       Result_In_Progress); 
  81.    pragma Convention (C, Gtk_Print_Operation_Result); 
  82.  
  83.    type Gtk_Print_Operation_Action is 
  84.      (Action_Print_Dialog, 
  85.       Action_Print, 
  86.       Action_Preview, 
  87.       Action_Export); 
  88.    pragma Convention (C, Gtk_Print_Operation_Action); 
  89.  
  90.    type Gtk_Print_Error is 
  91.      (Error_General, 
  92.       Error_Internal_Error, 
  93.       Error_Nomem, 
  94.       Error_Invalid_File); 
  95.    pragma Convention (C, Gtk_Print_Error); 
  96.  
  97.    procedure Gtk_New (Widget : out Gtk_Print_Operation); 
  98.    procedure Initialize (Widget : access Gtk_Print_Operation_Record'Class); 
  99.    --  Creates a new Gtk_Print_Operation. 
  100.  
  101.    function Get_Type return GType; 
  102.  
  103.    function Error_Quark return GQuark; 
  104.    --  Registers an error quark for Gtk_Print_Operation if necessary. 
  105.  
  106.    function Run 
  107.      (Op     : access Gtk_Print_Operation_Record; 
  108.       Action : Gtk_Print_Operation_Action; 
  109.       Parent : access Gtk.Window.Gtk_Window_Record'Class; 
  110.       Error  : Glib.Error.GError := null) 
  111.       return Gtk_Print_Operation_Result; 
  112.    --  Runs the print operation, by first letting the user modify 
  113.    --  print settings in the print dialog, and then by printing the 
  114.    --  document. 
  115.    -- 
  116.    --  Normally that this function does not return until the rendering of all 
  117.    --  pages is complete. You can connect to the status-changed signal on Op 
  118.    --  to obtain some information about the progress of the print operation. 
  119.    --  Furthermore, it may use a recursive mainloop to show the print dialog. 
  120.    -- 
  121.    --  If you call Set_Allow_Async or set the allow-async property the 
  122.    --  operation will run asynchronously if this is supported on the platform. 
  123.    --  The done signal will be emitted with the result of the operation when 
  124.    --  it is done (i.e. when the dialog is canceled, or when the print succeeds 
  125.    --  or fails). 
  126.    -- 
  127.    --     begin 
  128.    --        if Settings /= null then 
  129.    --           Set_Print_Settings (Print, Settings); 
  130.    --        end if; 
  131.    -- 
  132.    --        if Page_Setup /= null then 
  133.    --           Set_Default_Page_Setup (Print, Page_Setup); 
  134.    --        end if; 
  135.    -- 
  136.    --        Connect (Print, "begin-print", Begin_Print'Access, User_Data); 
  137.    --        Connect (Print, "draw-page",   Draw_Page'Access,   User_Data); 
  138.    -- 
  139.    --        Result := Run (Print, Action_Print_Dialog, Parent, Error); 
  140.    -- 
  141.    --        case Result is 
  142.    --           when Result_Error => 
  143.    --              Gtk_New 
  144.    --                (Error_Dialog, 
  145.    --                 Parent, 
  146.    --                 Destroy_With_Parent, 
  147.    --                 Message_Error, 
  148.    --                 Buttons_Close, 
  149.    --                 "Error printing file"); 
  150.    --              Connect 
  151.    --                (Error_Dialog, "response", Gtk_Widget_Destroy'Access); 
  152.    --              Show (Error_Dialog); 
  153.    --              Glib.Error.Error_Free (Error); 
  154.    -- 
  155.    --           when Result_Apply => 
  156.    --              if Settings /= null then 
  157.    --                 Unref (Settings); 
  158.    --              end if; 
  159.    --              Settings := Get_Print_Settings (Print); 
  160.    --              Ref (Settings); 
  161.    -- 
  162.    --           when Result_Cancel =>      null; 
  163.    --           when Result_In_Progress => null; 
  164.    --        end case; 
  165.    -- 
  166.    --  Note that Run can only be called once on a given Gtk_Print_Operation. 
  167.    -- 
  168.    --  Return value: the result of the print operation. A return value of 
  169.    --  Result_Apply indicates that the printing was completed successfully. 
  170.    --  In this case, it is a good idea to obtain the used print settings with 
  171.    --  Get_Print_Settings and store them for reuse with the next print 
  172.    --  operation. A value of Result_In_Progress means the operation is running 
  173.    --  asynchronously, and will emit the done signal when done. 
  174.  
  175.    procedure Cancel (Op : access Gtk_Print_Operation_Record); 
  176.    --  Cancels a running print operation. This function may be called from 
  177.    --  a begin-print, paginate or draw-page signal handler to stop the 
  178.    --  currently running print operation. 
  179.  
  180.    procedure Draw_Page_Finish (Op : access Gtk_Print_Operation_Record); 
  181.    --  Signal that drawing of particular page is complete. 
  182.    -- 
  183.    --  It is called after completion of page drawing (e.g. drawing in another 
  184.    --  thread).  If Set_Defer_Drawing was called before, then this function has 
  185.    --  to be called by application. In another case it is called by the library 
  186.    --  itself. 
  187.  
  188.    procedure Get_Error 
  189.      (Op    : access Gtk_Print_Operation_Record; 
  190.       Error : Glib.Error.GError); 
  191.    --  Call this when the result of a print operation is 
  192.    --  Result_Error, either as returned by Run, or in the done signal handler. 
  193.    --  The returned GError will contain more details on what went wrong. 
  194.  
  195.    function Get_Print_Settings 
  196.      (Op : access Gtk_Print_Operation_Record) 
  197.       return Gtk.Print_Settings.Gtk_Print_Settings; 
  198.    procedure Set_Print_Settings 
  199.      (Op             : access Gtk_Print_Operation_Record; 
  200.       Print_Settings : access 
  201.                        Gtk.Print_Settings.Gtk_Print_Settings_Record'Class); 
  202.    --  Manipulate the print settings for Op. This is typically used to 
  203.    --  re-establish print settings from a previous print operation, see Run. 
  204.    -- 
  205.    --  Note that the Get_Print_Setting's return value is null until either 
  206.    --  Set_Print_Settings or Run have been called. 
  207.  
  208.    function Get_Status 
  209.      (Op : access Gtk_Print_Operation_Record) return Gtk_Print_Status; 
  210.    function Get_Status (Op : access Gtk_Print_Operation_Record) return String; 
  211.    --  Returns the status of the print operation. 
  212.    -- 
  213.    --  A Gtk_Print_Status is suitable for programmatic use. 
  214.    -- 
  215.    --  The String returned is a translated string representation of the 
  216.    --  status of the print operation.  It is suitable for displaying the 
  217.    --  print status in, e.g., a Gtk_Statusbar. 
  218.  
  219.    function Is_Finished 
  220.      (Op : access Gtk_Print_Operation_Record) return Boolean; 
  221.    --  A convenience function to find out whether the print operation 
  222.    --  is finished, either successfully (Status_Finished) or unsuccessfully 
  223.    --  (Status_Finished_Aborted). 
  224.    -- 
  225.    --  Note: when you enable print status tracking the print operation 
  226.    --  can be in a non-finished state even after done has been called, as 
  227.    --  the operation status then tracks the print job status on the printer. 
  228.  
  229.    procedure Set_Allow_Async 
  230.      (Op          : access Gtk_Print_Operation_Record; 
  231.       Allow_Async : Boolean); 
  232.    --  Sets whether Run may return before the print operation is completed. 
  233.    --  Note that some platforms may not allow asynchronous operation. 
  234.  
  235.    procedure Set_Current_Page 
  236.      (Op           : access Gtk_Print_Operation_Record; 
  237.       Current_Page : Gint); 
  238.    --  Sets the current page. 
  239.    -- 
  240.    --  If this is called before Run, the user will be able to select to print 
  241.    --  only the current page. 
  242.    -- 
  243.    --  Note that this only makes sense for pre-paginated documents. 
  244.  
  245.    procedure Set_Custom_Tab_Label 
  246.      (Op    : access Gtk_Print_Operation_Record; 
  247.       Label : String); 
  248.    --  Sets the label for the tab holding custom widgets. 
  249.  
  250.    procedure Set_Defer_Drawing (Op : access Gtk_Print_Operation_Record); 
  251.    --  Sets up the Gtk_Print_Operation to wait for calling of Draw_Page_Finish 
  252.    --  from application. It can be used for drawing page in another thread. 
  253.    -- 
  254.    --  This function must be called in the callback of "draw-page" signal. 
  255.  
  256.    procedure Set_Export_Filename 
  257.      (Op       : access Gtk_Print_Operation_Record; 
  258.       Filename : String); 
  259.    --  Sets up the Gtk_Print_Operation to generate a file instead 
  260.    --  of showing the print dialog. The indended use of this function 
  261.    --  is for implementing "Export to PDF" actions. Currently, PDF 
  262.    --  is the only supported format. 
  263.    -- 
  264.    --  "Print to PDF" support is independent of this and is done 
  265.    --  by letting the user pick the "Print to PDF" item from the list 
  266.    --  of printers in the print dialog. 
  267.  
  268.    procedure Set_Job_Name 
  269.      (Op       : access Gtk_Print_Operation_Record; 
  270.       Job_Name : String); 
  271.    --  Sets the name of the print job. The name is used to identify 
  272.    --  the job (e.g. in monitoring applications like eggcups). 
  273.    -- 
  274.    --  If you don't set a job name, GTK+ picks a default one by 
  275.    --  numbering successive print jobs. 
  276.  
  277.    procedure Set_N_Pages 
  278.      (Op      : access Gtk_Print_Operation_Record; 
  279.       N_Pages : Gint); 
  280.    --  Sets the number of pages in the document. 
  281.    -- 
  282.    --  This MUST be set to a positive number before the rendering starts. 
  283.    --  It may be set in a begin-print signal hander. 
  284.    -- 
  285.    --  Note that the page numbers passed to the request-page-setup and 
  286.    --  draw-page signals are 0-based, i.e. if the user chooses to print all 
  287.    --  pages, the last draw-page signal will be for page N_Pages - 1. 
  288.  
  289.    procedure Set_Show_Progress 
  290.      (Op            : access Gtk_Print_Operation_Record; 
  291.       Show_Progress : Boolean); 
  292.    --  If True, the print operation will show a progress dialog during the 
  293.    --  print operation. 
  294.  
  295.    procedure Set_Track_Print_Status 
  296.      (Op           : access Gtk_Print_Operation_Record; 
  297.       Track_Status : Boolean); 
  298.    --  If True, the print operation will try to continue report on the status 
  299.    --  of the print job in the printer queues and printer. This can allow your 
  300.    --  application to show things like "out of paper" issues, and when the 
  301.    --  print job actually reaches the printer. 
  302.    -- 
  303.    --  This function is often implemented using some form of polling, so it 
  304.    --  should not be enabled unless needed. 
  305.  
  306.    procedure Set_Unit 
  307.      (Op   : access Gtk_Print_Operation_Record; 
  308.       Unit : Gtk.Enums.Gtk_Unit); 
  309.    --  Sets up the transformation for the cairo context obtained from 
  310.    --  Gtk_Print_Context in such a way that distances are measured in 
  311.    --  units of Unit. 
  312.  
  313.    procedure Set_Use_Full_Page 
  314.      (Op        : access Gtk_Print_Operation_Record; 
  315.       Full_Page : Boolean); 
  316.    --  If True, the transformation for the cairo context obtained from 
  317.    --  Gtk_Print_Context puts the origin at the top left corner of the page 
  318.    --  (which may not be the top left corner of the sheet, depending on page 
  319.    --  orientation and the number of pages per sheet). Otherwise, the origin 
  320.    --  is at the top left corner of the imageable area (i.e. inside the 
  321.    --  margins). 
  322.  
  323.    ---------------- 
  324.    -- Page Setup -- 
  325.    ---------------- 
  326.  
  327.    function Get_Default_Page_Setup 
  328.      (Op : access Gtk_Print_Operation_Record) 
  329.       return Gtk.Page_Setup.Gtk_Page_Setup; 
  330.    procedure Set_Default_Page_Setup 
  331.      (Op                 : access Gtk_Print_Operation_Record; 
  332.       Default_Page_Setup : access Gtk.Page_Setup.Gtk_Page_Setup_Record'Class); 
  333.    --  Makes Default_Page_Setup the default page setup for Op. 
  334.    --  Default_Page_Setup may be null. 
  335.    -- 
  336.    --  This page setup will be used by Run, but it can be overridden on a 
  337.    --  per-page basis by connecting to the request-page-setup signal. 
  338.  
  339.    function Run_Page_Setup_Dialog 
  340.      (Parent     : access Gtk.Window.Gtk_Window_Record'Class; 
  341.       Page_Setup : access Gtk.Page_Setup.Gtk_Page_Setup_Record'Class; 
  342.       Settings   : access Gtk.Print_Settings.Gtk_Print_Settings_Record'Class) 
  343.       return Gtk.Page_Setup.Gtk_Page_Setup; 
  344.    --  Runs a page setup dialog, letting the user modify the values from 
  345.    --  Page_Setup. If the user cancels the dialog, the returned Gtk_Page_Setup 
  346.    --  is identical to the passed in Page_Setup, otherwise it contains the 
  347.    --  modifications done in the dialog. 
  348.    -- 
  349.    --  Note that this function may use a recursive mainloop to show the page 
  350.    --  setup dialog. 
  351.  
  352.    ---------------- 
  353.    -- Properties -- 
  354.    ---------------- 
  355.  
  356.    --  <properties> 
  357.    --  Name:  Allow_Async_Property 
  358.    --  Type:  Boolean 
  359.    --  Descr: True if print process may run asynchronous. 
  360.    -- 
  361.    --  Name:  Current_Page_Property 
  362.    --  Type:  Int 
  363.    --  Descr: The current page in the document 
  364.    -- 
  365.    --  Name:  Custom_Tab_Label_Property 
  366.    --  Type:  String 
  367.    --  Descr: Label for the tab containing custom widgets. 
  368.    -- 
  369.    --  Name:  Default_Page_Setup_Property 
  370.    --  Type:  Object 
  371.    --  Descr: The Gtk_Page_Setup used by default 
  372.    -- 
  373.    --  Name:  Export_Filename_Property 
  374.    --  Type:  String 
  375.    --  Descr: Export filename 
  376.    -- 
  377.    --  Name:  Job_Name_Property 
  378.    --  Type:  String 
  379.    --  Descr: A string used for identifying the print job. 
  380.    -- 
  381.    --  Name:  N_Pages_Property 
  382.    --  Type:  Int 
  383.    --  Descr: The number of pages in the document. 
  384.    -- 
  385.    --  Name:  Print_Settings_Property 
  386.    --  Type:  Object 
  387.    --  Descr: The Gtk_Print_Settings used for initializing the dialog 
  388.    -- 
  389.    --  Name:  Show_Progress_Property 
  390.    --  Type:  Boolean 
  391.    --  Descr: True if a progress dialog is shown while printing. 
  392.    -- 
  393.    --  Name:  Status_Property 
  394.    --  Type:  Enum 
  395.    --  Descr: The status of the print operation 
  396.    -- 
  397.    --  Name:  Status_String_Property 
  398.    --  Type:  String 
  399.    --  Descr: A human-readable description of the status 
  400.    -- 
  401.    --  Name:  Track_Print_Status_Property 
  402.    --  Type:  Boolean 
  403.    --  Descr: True if the print operation will continue to report on the 
  404.    --         print job status after the print data has been sent to the 
  405.    --         printer or print server. 
  406.    -- 
  407.    --  Name:  Unit_Property 
  408.    --  Type:  Enum 
  409.    --  Descr: The unit in which distances can be measured in the context 
  410.    -- 
  411.    --  Name:  Use_Full_Page_Property 
  412.    --  Type:  Boolean 
  413.    --  Descr: True if the origin of the context should be at the corner of 
  414.    --         the page and not the corner of the imageable area 
  415.    -- 
  416.    --  </properties> 
  417.  
  418.    Allow_Async_Property        : constant Glib.Properties.Property_Boolean; 
  419.    Current_Page_Property       : constant Glib.Properties.Property_Int; 
  420.    Custom_Tab_Label_Property   : constant Glib.Properties.Property_String; 
  421.    Default_Page_Setup_Property : constant Glib.Properties.Property_Object; 
  422.    Export_Filename_Property    : constant Glib.Properties.Property_String; 
  423.    Job_Name_Property           : constant Glib.Properties.Property_String; 
  424.    N_Pages_Property            : constant Glib.Properties.Property_Int; 
  425.    Print_Settings_Property     : constant Glib.Properties.Property_Object; 
  426.    Show_Progress_Property      : constant Glib.Properties.Property_Boolean; 
  427.    Status_Property             : constant Glib.Properties.Property_Enum; 
  428.    Status_String_Property      : constant Glib.Properties.Property_String; 
  429.    Track_Print_Status_Property : constant Glib.Properties.Property_Boolean; 
  430.    Unit_Property               : constant Glib.Properties.Property_Enum; 
  431.    Use_Full_Page_Property      : constant Glib.Properties.Property_Boolean; 
  432.  
  433. private 
  434.  
  435.    type Gtk_Print_Operation_Record is 
  436.      new Glib.Object.GObject_Record with null record; 
  437.  
  438.    Allow_Async_Property : constant Glib.Properties.Property_Boolean := 
  439.      Glib.Properties.Build ("allow-async"); 
  440.    Current_Page_Property : constant Glib.Properties.Property_Int := 
  441.      Glib.Properties.Build ("current-page"); 
  442.    Custom_Tab_Label_Property : constant Glib.Properties.Property_String := 
  443.      Glib.Properties.Build ("custom-tab-label"); 
  444.    Default_Page_Setup_Property : constant Glib.Properties.Property_Object := 
  445.      Glib.Properties.Build ("default-page-setup"); 
  446.    Export_Filename_Property : constant Glib.Properties.Property_String := 
  447.      Glib.Properties.Build ("export-filename"); 
  448.    Job_Name_Property : constant Glib.Properties.Property_String := 
  449.      Glib.Properties.Build ("job-name"); 
  450.    N_Pages_Property : constant Glib.Properties.Property_Int := 
  451.      Glib.Properties.Build ("n-pages"); 
  452.    Print_Settings_Property : constant Glib.Properties.Property_Object := 
  453.      Glib.Properties.Build ("print-settings"); 
  454.    Show_Progress_Property : constant Glib.Properties.Property_Boolean := 
  455.      Glib.Properties.Build ("show-progress"); 
  456.    Status_Property : constant Glib.Properties.Property_Enum := 
  457.      Glib.Properties.Build ("status"); 
  458.    Status_String_Property : constant Glib.Properties.Property_String := 
  459.      Glib.Properties.Build ("status-string"); 
  460.    Track_Print_Status_Property : constant Glib.Properties.Property_Boolean := 
  461.      Glib.Properties.Build ("track-print-status"); 
  462.    Unit_Property : constant Glib.Properties.Property_Enum := 
  463.      Glib.Properties.Build ("unit"); 
  464.    Use_Full_Page_Property : constant Glib.Properties.Property_Boolean := 
  465.      Glib.Properties.Build ("use-full-page"); 
  466.  
  467.    pragma Import (C, Get_Type, "gtk_print_operation_get_type"); 
  468.    pragma Import (C, Error_Quark, "gtk_print_error_quark"); 
  469.  
  470. end Gtk.Print_Operation;