## Documentation

Table of Contents
Class Inheritance Tree
Widget Screenshots
Package groups

## Index

Package: Print_Operation

- Goto spec source

# Description

    package Gtk.Print_Operation is

Gtk_Print_Operation is the high-level, portable printing API. It looks a bit different than other GTK+ dialogs such as the Gtk_File_Chooser, since some platforms don't expose enough infrastructure to implement a good print dialog. On such platforms, Gtk_Print_Operation uses the native print dialog. On platforms which do not provide a native print dialog, GTK+ uses its own, see Gtk_Print_Unix_Dialog.

The typical way to use the high-level printing API is to create a Gtk_Print_Operation object with Gtk_New when the user selects to print.

Then you set some properties on it, e.g. the page size, any Gtk_Print_Settings from previous print operations, the number of pages, the current page, etc.

Then you start the print operation by calling Run. It will then show a dialog, let the user select a printer and options. When the user finished the dialog various signals will be emitted on the Gtk_Print_Operation, the main one being draw-page, which you are supposed to catch and render the page on the provided Gtk_Print_Context using Cairo.

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 Run.

Binding from C File version 2.16.6

# Classes

### Gtk_Print_Operation_Record

- Goto declaration in source
- Goto full declaration in source

    type Gtk_Print_Operation_Record is
         new Glib.Object.GObject_Record with private;

#### Ancestors:

Glib.Object.GObject_Record

#### Immediate Children:

Gtkada.Printing.Gtkada_Print_Operation_Record

#### Primitive operations:

Cancel

- To API doc
- To spec

Draw_Page_Finish

- To API doc
- To spec

Get_Default_Page_Setup

- To API doc
- To spec

Get_Error

- To API doc
- To spec

Get_Print_Settings

- To API doc
- To spec

Get_Status

- To API doc
- To spec

Get_Status

- To API doc
- To spec

Glib.Object.Deallocate

- To API doc
- To spec

(Inherited)
Glib.Object.Get_Type

- To API doc
- To spec

(Inherited)
Glib.Object.Notify

- To API doc
- To spec

(Inherited)
Glib.Object.Ref

- To API doc
- To spec

(Inherited)
Glib.Object.Ref_Sink

- To API doc
- To spec

(Inherited)
Glib.Object.Unref

- To API doc
- To spec

(Inherited)
Is_Finished

- To API doc
- To spec

Run

- To API doc
- To spec

Set_Allow_Async

- To API doc
- To spec

Set_Current_Page

- To API doc
- To spec

Set_Custom_Tab_Label

- To API doc
- To spec

Set_Default_Page_Setup

- To API doc
- To spec

Set_Defer_Drawing

- To API doc
- To spec

Set_Export_Filename

- To API doc
- To spec

Set_Job_Name

- To API doc
- To spec

Set_N_Pages

- To API doc
- To spec

Set_Print_Settings

- To API doc
- To spec

Set_Show_Progress

- To API doc
- To spec

Set_Track_Print_Status

- To API doc
- To spec

Set_Unit

- To API doc
- To spec

Set_Use_Full_Page

- To API doc
- To spec

# Types

### Gtk_Print_Operation

- Goto declaration in source

    type Gtk_Print_Operation is access all Gtk_Print_Operation_Record'Class;

### Gtk_Print_Status

- Goto declaration in source

    type Gtk_Print_Status is
         (Status_Initial,
          Status_Preparing,
          Status_Generating_Data,
          Status_Sending_Data,
          Status_Pending,
          Status_Pending_Issue,
          Status_Printing,
          Status_Finished,
          Status_Finished_Aborted);

### Gtk_Print_Operation_Result

- Goto declaration in source

    type Gtk_Print_Operation_Result is
         (Result_Error,
          Result_Apply,
          Result_Cancel,
          Result_In_Progress);

### Gtk_Print_Operation_Action

- Goto declaration in source

    type Gtk_Print_Operation_Action is
         (Action_Print_Dialog,
          Action_Print,
          Action_Preview,
          Action_Export);

### Gtk_Print_Error

- Goto declaration in source

    type Gtk_Print_Error is
         (Error_General,
          Error_Internal_Error,
          Error_Nomem,
          Error_Invalid_File);

# Constants & Global variables

### Allow_Async_Property

- Goto declaration in source

(Glib.Properties.Property_Boolean)

    Allow_Async_Property        : constant Glib.Properties.Property_Boolean;

### Current_Page_Property

- Goto declaration in source

(Glib.Properties.Property_Int)

    Current_Page_Property       : constant Glib.Properties.Property_Int;

### Custom_Tab_Label_Property

- Goto declaration in source

(Glib.Properties.Property_String)

    Custom_Tab_Label_Property   : constant Glib.Properties.Property_String;

### Default_Page_Setup_Property

- Goto declaration in source

(Glib.Properties.Property_Object)

    Default_Page_Setup_Property : constant Glib.Properties.Property_Object;

### Export_Filename_Property

- Goto declaration in source

(Glib.Properties.Property_String)

    Export_Filename_Property    : constant Glib.Properties.Property_String;

### Job_Name_Property

- Goto declaration in source

(Glib.Properties.Property_String)

    Job_Name_Property           : constant Glib.Properties.Property_String;

### N_Pages_Property

- Goto declaration in source

(Glib.Properties.Property_Int)

    N_Pages_Property            : constant Glib.Properties.Property_Int;

### Print_Settings_Property

- Goto declaration in source

(Glib.Properties.Property_Object)

    Print_Settings_Property     : constant Glib.Properties.Property_Object;

### Show_Progress_Property

- Goto declaration in source

(Glib.Properties.Property_Boolean)

    Show_Progress_Property      : constant Glib.Properties.Property_Boolean;

### Status_Property

- Goto declaration in source

(Glib.Properties.Property_Enum)

    Status_Property             : constant Glib.Properties.Property_Enum;

### Status_String_Property

- Goto declaration in source

(Glib.Properties.Property_String)

    Status_String_Property      : constant Glib.Properties.Property_String;

### Track_Print_Status_Property

- Goto declaration in source

(Glib.Properties.Property_Boolean)

    Track_Print_Status_Property : constant Glib.Properties.Property_Boolean;

### Unit_Property

- Goto declaration in source

(Glib.Properties.Property_Enum)

    Unit_Property               : constant Glib.Properties.Property_Enum;

### Use_Full_Page_Property

- Goto declaration in source

(Glib.Properties.Property_Boolean)

    Use_Full_Page_Property      : constant Glib.Properties.Property_Boolean;

# Subprograms & Entries

### Gtk_New

- Goto spec in source

    procedure Gtk_New (Widget: out Gtk_Print_Operation);

### Initialize

- Goto spec in source

    procedure Initialize (Widget: access Gtk_Print_Operation_Record'Class);

Creates a new Gtk_Print_Operation.

### Get_Type

- Goto spec in source
- Goto body in source

    function Get_Type return GType;

### Error_Quark

- Goto spec in source
- Goto body in source

    function Error_Quark return GQuark;

Registers an error quark for Gtk_Print_Operation if necessary.

### Run

- Goto spec in source

    function Run (Op: access Gtk_Print_Operation_Record;Action: Gtk_Print_Operation_Action;Parent: access Gtk.Window.Gtk_Window_Record'Class;Error: Glib.Error.GError := null) return Gtk_Print_Operation_Result;

Runs the print operation, by first letting the user modify print settings in the print dialog, and then by printing the document. Normally that this function does not return until the rendering of all pages is complete. You can connect to the status-changed signal on Op to obtain some information about the progress of the print operation. Furthermore, it may use a recursive mainloop to show the print dialog. If you call Set_Allow_Async or set the allow-async property the operation will run asynchronously if this is supported on the platform. The done signal will be emitted with the result of the operation when it is done (i.e. when the dialog is canceled, or when the print succeeds or fails). begin if Settings /= null then Set_Print_Settings (Print, Settings); end if; if Page_Setup /= null then Set_Default_Page_Setup (Print, Page_Setup); end if; Connect (Print, "begin-print", Begin_Print'Access, User_Data); Connect (Print, "draw-page", Draw_Page'Access, User_Data); Result := Run (Print, Action_Print_Dialog, Parent, Error); case Result is when Result_Error => Gtk_New (Error_Dialog, Parent, Destroy_With_Parent, Message_Error, Buttons_Close, "Error printing file"); Connect (Error_Dialog, "response", Gtk_Widget_Destroy'Access); Show (Error_Dialog); Glib.Error.Error_Free (Error); when Result_Apply => if Settings /= null then Unref (Settings); end if; Settings := Get_Print_Settings (Print); Ref (Settings); when Result_Cancel => null; when Result_In_Progress => null; end case; Note that Run can only be called once on a given Gtk_Print_Operation. Return value: the result of the print operation. A return value of Result_Apply indicates that the printing was completed successfully. In this case, it is a good idea to obtain the used print settings with Get_Print_Settings and store them for reuse with the next print operation. A value of Result_In_Progress means the operation is running asynchronously, and will emit the done signal when done.

### Cancel

- Goto spec in source

    procedure Cancel (Op: access Gtk_Print_Operation_Record);

Cancels a running print operation. This function may be called from a begin-print, paginate or draw-page signal handler to stop the currently running print operation.

### Draw_Page_Finish

- Goto spec in source

    procedure Draw_Page_Finish (Op: access Gtk_Print_Operation_Record);

Signal that drawing of particular page is complete. It is called after completion of page drawing (e.g. drawing in another thread). If Set_Defer_Drawing was called before, then this function has to be called by application. In another case it is called by the library itself.

### Get_Error

- Goto spec in source

    procedure Get_Error (Op: access Gtk_Print_Operation_Record;Error: Glib.Error.GError);

Call this when the result of a print operation is Result_Error, either as returned by Run, or in the done signal handler. The returned GError will contain more details on what went wrong.

### Get_Print_Settings

- Goto spec in source

    function Get_Print_Settings (Op: access Gtk_Print_Operation_Record) return Gtk.Print_Settings.Gtk_Print_Settings;

### Set_Print_Settings

- Goto spec in source

    procedure Set_Print_Settings (Op: access Gtk_Print_Operation_Record;Print_Settings: access Gtk.Print_Settings.Gtk_Print_Settings_Record'Class);

Manipulate the print settings for Op. This is typically used to re-establish print settings from a previous print operation, see Run. Note that the Get_Print_Setting's return value is null until either Set_Print_Settings or Run have been called.

### Get_Status

- Goto spec in source

    function Get_Status (Op: access Gtk_Print_Operation_Record) return Gtk_Print_Status;

### Get_Status

- Goto spec in source

    function Get_Status (Op: access Gtk_Print_Operation_Record) return String;

Returns the status of the print operation. A Gtk_Print_Status is suitable for programmatic use. The String returned is a translated string representation of the status of the print operation. It is suitable for displaying the print status in, e.g., a Gtk_Statusbar.

### Is_Finished

- Goto spec in source

    function Is_Finished (Op: access Gtk_Print_Operation_Record) return Boolean;

A convenience function to find out whether the print operation is finished, either successfully (Status_Finished) or unsuccessfully (Status_Finished_Aborted). Note: when you enable print status tracking the print operation can be in a non-finished state even after done has been called, as the operation status then tracks the print job status on the printer.

### Set_Allow_Async

- Goto spec in source

    procedure Set_Allow_Async (Op: access Gtk_Print_Operation_Record;Allow_Async: Boolean);

Sets whether Run may return before the print operation is completed. Note that some platforms may not allow asynchronous operation.

### Set_Current_Page

- Goto spec in source

    procedure Set_Current_Page (Op: access Gtk_Print_Operation_Record;Current_Page: Gint);

Sets the current page. If this is called before Run, the user will be able to select to print only the current page. Note that this only makes sense for pre-paginated documents.

### Set_Custom_Tab_Label

- Goto spec in source

    procedure Set_Custom_Tab_Label (Op: access Gtk_Print_Operation_Record;Label: String);

Sets the label for the tab holding custom widgets.

### Set_Defer_Drawing

- Goto spec in source

    procedure Set_Defer_Drawing (Op: access Gtk_Print_Operation_Record);

Sets up the Gtk_Print_Operation to wait for calling of Draw_Page_Finish from application. It can be used for drawing page in another thread. This function must be called in the callback of "draw-page" signal.

### Set_Export_Filename

- Goto spec in source

    procedure Set_Export_Filename (Op: access Gtk_Print_Operation_Record;Filename: String);

Sets up the Gtk_Print_Operation to generate a file instead of showing the print dialog. The indended use of this function is for implementing "Export to PDF" actions. Currently, PDF is the only supported format. "Print to PDF" support is independent of this and is done by letting the user pick the "Print to PDF" item from the list of printers in the print dialog.

### Set_Job_Name

- Goto spec in source

    procedure Set_Job_Name (Op: access Gtk_Print_Operation_Record;Job_Name: String);

Sets the name of the print job. The name is used to identify the job (e.g. in monitoring applications like eggcups). If you don't set a job name, GTK+ picks a default one by numbering successive print jobs.

### Set_N_Pages

- Goto spec in source

    procedure Set_N_Pages (Op: access Gtk_Print_Operation_Record;N_Pages: Gint);

Sets the number of pages in the document. This MUST be set to a positive number before the rendering starts. It may be set in a begin-print signal hander. Note that the page numbers passed to the request-page-setup and draw-page signals are 0-based, i.e. if the user chooses to print all pages, the last draw-page signal will be for page N_Pages - 1.

### Set_Show_Progress

- Goto spec in source

    procedure Set_Show_Progress (Op: access Gtk_Print_Operation_Record;Show_Progress: Boolean);

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

### Set_Track_Print_Status

- Goto spec in source

    procedure Set_Track_Print_Status (Op: access Gtk_Print_Operation_Record;Track_Status: Boolean);

If True, the print operation will try to continue report on the status of the print job in the printer queues and printer. This can allow your application to show things like "out of paper" issues, and when the print job actually reaches the printer. This function is often implemented using some form of polling, so it should not be enabled unless needed.

### Set_Unit

- Goto spec in source

    procedure Set_Unit (Op: access Gtk_Print_Operation_Record;Unit: Gtk.Enums.Gtk_Unit);

Sets up the transformation for the cairo context obtained from Gtk_Print_Context in such a way that distances are measured in units of Unit.

### Set_Use_Full_Page

- Goto spec in source

    procedure Set_Use_Full_Page (Op: access Gtk_Print_Operation_Record;Full_Page: Boolean);

If True, the transformation for the cairo context obtained from Gtk_Print_Context puts the origin at the top left corner of the page (which may not be the top left corner of the sheet, depending on page orientation and the number of pages per sheet). Otherwise, the origin is at the top left corner of the imageable area (i.e. inside the margins).

### Get_Default_Page_Setup

- Goto spec in source

    function Get_Default_Page_Setup (Op: access Gtk_Print_Operation_Record) return Gtk.Page_Setup.Gtk_Page_Setup;

### Set_Default_Page_Setup

- Goto spec in source

    procedure Set_Default_Page_Setup (Op: access Gtk_Print_Operation_Record;Default_Page_Setup: access Gtk.Page_Setup.Gtk_Page_Setup_Record'Class);

Makes Default_Page_Setup the default page setup for Op. Default_Page_Setup may be null. This page setup will be used by Run, but it can be overridden on a per-page basis by connecting to the request-page-setup signal.

### Run_Page_Setup_Dialog

- Goto spec in source

    function Run_Page_Setup_Dialog (Parent: access Gtk.Window.Gtk_Window_Record'Class;Page_Setup: access Gtk.Page_Setup.Gtk_Page_Setup_Record'Class;Settings: access Gtk.Print_Settings.Gtk_Print_Settings_Record'Class) return Gtk.Page_Setup.Gtk_Page_Setup;

Runs a page setup dialog, letting the user modify the values from Page_Setup. If the user cancels the dialog, the returned Gtk_Page_Setup is identical to the passed in Page_Setup, otherwise it contains the modifications done in the dialog. Note that this function may use a recursive mainloop to show the page setup dialog.