GtkPrinter: GTK+ 2 Reference Manual

## GtkPrinter GtkPrinter — Represents a printer |

## Functions

GtkPrinter * | gtk_printer_new ()
GtkPrintBackend * | gtk_printer_get_backend ()
const gchar * | gtk_printer_get_name ()
const gchar * | gtk_printer_get_state_message ()
const gchar * | gtk_printer_get_description ()
const gchar * | gtk_printer_get_location ()
const gchar * | gtk_printer_get_icon_name ()
gint | gtk_printer_get_job_count ()
gboolean | gtk_printer_is_active ()
gboolean | gtk_printer_is_paused ()
gboolean | gtk_printer_is_accepting_jobs ()
gboolean | gtk_printer_is_virtual ()
gboolean | gtk_printer_is_default ()
gboolean | gtk_printer_accepts_ps ()
gboolean | gtk_printer_accepts_pdf ()
GList * | gtk_printer_list_papers ()
gint | gtk_printer_compare ()
gboolean | gtk_printer_has_details ()
void | gtk_printer_request_details ()
GtkPrintCapabilities | gtk_printer_get_capabilities ()
GtkPageSetup * | gtk_printer_get_default_page_size ()
gboolean | gtk_printer_get_hard_margins ()
gboolean | (*GtkPrinterFunc) ()
void | gtk_enumerate_printers ()

## Properties

gboolean | accepting-jobs | Read
gboolean | accepts-pdf | Read / Write / Construct Only
gboolean | accepts-ps | Read / Write / Construct Only
GtkPrintBackend * | backend | Read / Write / Construct Only
gchar * | icon-name | Read
gboolean | is-virtual | Read / Write / Construct Only
gint | job-count | Read
gchar * | location | Read
gchar * | name | Read / Write / Construct Only
gboolean | paused | Read
gchar * | state-message | Read

## Signals

void | details-acquired | Run Last

## Types and Values

struct | GtkPrinter
| GtkPrintBackend

## Object Hierarchy

        GObject
        ├── GtkPrintBackend
        ╰── GtkPrinter

## Includes

    #include <gtk/gtk.h>

## Description

A GtkPrinter object represents a printer. You only need to deal directly with printers if you use the non-portable GtkPrintUnixDialog API.

A GtkPrinter allows to get status information about the printer, such as its description, its location, the number of queued jobs, etc. Most importantly, a GtkPrinter object can be used to create a GtkPrintJob object, which lets you print to the printer.

Printing support was added in GTK+ 2.10.

## Functions

### gtk_printer_new ()

    GtkPrinter *
    gtk_printer_new (const gchar *name,
                     GtkPrintBackend *backend,
                     gboolean virtual_);

Creates a new GtkPrinter.

#### Parameters

name | the name of the printer |
backend | a GtkPrintBackend |
virtual_ | whether the printer is virtual |

#### Returns

a new GtkPrinter

Since 2.10

### gtk_printer_get_backend ()

    GtkPrintBackend *
    gtk_printer_get_backend (GtkPrinter *printer);

Returns the backend of the printer.

#### Parameters

printer | a GtkPrinter |

#### Returns

the backend of `printer` .

[transfer none]

Since 2.10

### gtk_printer_get_name ()

    const gchar *
    gtk_printer_get_name (GtkPrinter *printer);

Returns the name of the printer.

#### Parameters

printer | a GtkPrinter |

#### Returns

the name of `printer`

Since 2.10

### gtk_printer_get_state_message ()

    const gchar *
    gtk_printer_get_state_message (GtkPrinter *printer);

Returns the state message describing the current state of the printer.

#### Parameters

printer | a GtkPrinter |

#### Returns

the state message of `printer`

Since 2.10

### gtk_printer_get_description ()

    const gchar *
    gtk_printer_get_description (GtkPrinter *printer);

Gets the description of the printer.

#### Parameters

printer | a GtkPrinter |

#### Returns

the description of `printer`

Since 2.10

### gtk_printer_get_location ()

    const gchar *
    gtk_printer_get_location (GtkPrinter *printer);

Returns a description of the location of the printer.

#### Parameters

printer | a GtkPrinter |

#### Returns

the location of `printer`

Since 2.10

### gtk_printer_get_icon_name ()

    const gchar *
    gtk_printer_get_icon_name (GtkPrinter *printer);

Gets the name of the icon to use for the printer.

#### Parameters

printer | a GtkPrinter |

#### Returns

the icon name for `printer`

Since 2.10

### gtk_printer_get_job_count ()

    gint
    gtk_printer_get_job_count (GtkPrinter *printer);

Gets the number of jobs currently queued on the printer.

#### Parameters

printer | a GtkPrinter |

#### Returns

the number of jobs on `printer`

Since 2.10

### gtk_printer_is_active ()

    gboolean
    gtk_printer_is_active (GtkPrinter *printer);

Returns whether the printer is currently active (i.e. accepts new jobs).

#### Parameters

printer | a GtkPrinter |

#### Returns

`TRUE` if `printer` is active

Since 2.10

### gtk_printer_is_paused ()

    gboolean
    gtk_printer_is_paused (GtkPrinter *printer);

Returns whether the printer is currently paused. A paused printer still accepts jobs, but it is not printing them.

#### Parameters

printer | a GtkPrinter |

#### Returns

`TRUE` if `printer` is paused

Since 2.14

### gtk_printer_is_accepting_jobs ()

    gboolean
    gtk_printer_is_accepting_jobs (GtkPrinter *printer);

Returns whether the printer is accepting jobs

#### Parameters

printer | a GtkPrinter |

#### Returns

`TRUE` if `printer` is accepting jobs

Since 2.14

### gtk_printer_is_virtual ()

    gboolean
    gtk_printer_is_virtual (GtkPrinter *printer);

Returns whether the printer is virtual (i.e. does not represent actual printer hardware, but something like a CUPS class).

#### Parameters

printer | a GtkPrinter |

#### Returns

`TRUE` if `printer` is virtual

Since 2.10

### gtk_printer_is_default ()

    gboolean
    gtk_printer_is_default (GtkPrinter *printer);

Returns whether the printer is the default printer.

#### Parameters

printer | a GtkPrinter |

#### Returns

`TRUE` if `printer` is the default

Since 2.10

### gtk_printer_accepts_ps ()

    gboolean
    gtk_printer_accepts_ps (GtkPrinter *printer);

Returns whether the printer accepts input in PostScript format.

#### Parameters

printer | a GtkPrinter |

#### Returns

`TRUE` if `printer` accepts PostScript

Since 2.10

### gtk_printer_accepts_pdf ()

    gboolean
    gtk_printer_accepts_pdf (GtkPrinter *printer);

Returns whether the printer accepts input in PDF format.

#### Parameters

printer | a GtkPrinter |

#### Returns

`TRUE` if `printer` accepts PDF

Since 2.10

### gtk_printer_list_papers ()

    GList *
    gtk_printer_list_papers (GtkPrinter *printer);

Lists all the paper sizes `printer` supports. This will return and empty list unless the printer's details are available, see `gtk_printer_has_details()` and `gtk_printer_request_details()`.

#### Parameters

printer | a GtkPrinter |

#### Returns

a newly allocated list of newly allocated GtkPageSetup s.

[element-type GtkPageSetup][transfer full]

Since 2.12

### gtk_printer_compare ()

    gint
    gtk_printer_compare (GtkPrinter *a,
                         GtkPrinter *b);

Compares two printers.

#### Parameters

a | a GtkPrinter |
b | another GtkPrinter |

#### Returns

0 if the printer match, a negative value if `a` < `b` , or a positive value if `a` > `b`

Since 2.10

### gtk_printer_has_details ()

    gboolean
    gtk_printer_has_details (GtkPrinter *printer);

Returns whether the printer details are available.

#### Parameters

printer | a GtkPrinter |

#### Returns

`TRUE` if `printer` details are available

Since 2.12

### gtk_printer_request_details ()

    void
    gtk_printer_request_details (GtkPrinter *printer);

Requests the printer details. When the details are available, the “details-acquired” signal will be emitted on `printer` .

#### Parameters

printer | a GtkPrinter |

Since 2.12

### gtk_printer_get_capabilities ()

    GtkPrintCapabilities
    gtk_printer_get_capabilities (GtkPrinter *printer);

Returns the printer's capabilities.

This is useful when you're using GtkPrintUnixDialog's manual-capabilities setting and need to know which settings the printer can handle and which you must handle yourself.

This will return 0 unless the printer's details are available, see `gtk_printer_has_details()` and `gtk_printer_request_details()`.

#### Parameters

printer | a GtkPrinter |

#### Returns

the printer's capabilities

Since 2.12

### gtk_printer_get_default_page_size ()

    GtkPageSetup *
    gtk_printer_get_default_page_size (GtkPrinter *printer);

Returns default page size of `printer` .

#### Parameters

printer | a GtkPrinter |

#### Returns

a newly allocated GtkPageSetup with default page size of the printer.

Since 2.14

### gtk_printer_get_hard_margins ()

    gboolean
    gtk_printer_get_hard_margins (GtkPrinter *printer,
                                  gdouble *top,
                                  gdouble *bottom,
                                  gdouble *left,
                                  gdouble *right);

Retrieve the hard margins of `printer` , i.e. the margins that define the area at the borders of the paper that the printer cannot print to.

Note: This will not succeed unless the printer's details are available, see `gtk_printer_has_details()` and `gtk_printer_request_details()`.

#### Parameters

printer | a GtkPrinter |
top | a location to store the top margin in. | [out]
bottom | a location to store the bottom margin in. | [out]
left | a location to store the left margin in. | [out]
right | a location to store the right margin in. | [out]

#### Returns

`TRUE` iff the hard margins were retrieved

Since 2.20

### GtkPrinterFunc ()

    gboolean
    (*GtkPrinterFunc) (GtkPrinter *printer,
                       gpointer data);

The type of function passed to `gtk_enumerate_printers()`. Note that you need to ref `printer`, if you want to keep a reference to it after the function has returned.

#### Parameters

printer | a GtkPrinter |
data | user data passed to `gtk_enumerate_printers()` |

#### Returns

`TRUE` to stop the enumeration, `FALSE` to continue

### gtk_enumerate_printers ()

    void
    gtk_enumerate_printers (GtkPrinterFunc func,
                            gpointer data,
                            GDestroyNotify destroy,
                            gboolean wait);

Calls a function for all GtkPrinters. If `func` returns `TRUE`, the enumeration is stopped.

#### Parameters

func | a function to call for each printer |
data | user data to pass to `func` |
destroy | function to call if `data` is no longer needed |
wait | if `TRUE`, wait in a recursive mainloop until all printers are enumerated; otherwise return early |

Since 2.10

## Types and Values

### struct GtkPrinter

    struct GtkPrinter;

### GtkPrintBackend

    typedef struct _GtkPrintBackend GtkPrintBackend;

## Property Details

### The `“accepting-jobs”` property

      “accepting-jobs”           gboolean

This property is `TRUE` if the printer is accepting jobs.

Flags: Read

Default value: TRUE

Since 2.14

### The `“accepts-pdf”` property

      “accepts-pdf”              gboolean

TRUE if this printer can accept PDF.

Flags: Read / Write / Construct Only

Default value: FALSE

### The `“accepts-ps”` property

      “accepts-ps”               gboolean

TRUE if this printer can accept PostScript.

Flags: Read / Write / Construct Only

Default value: TRUE

### The `“backend”` property

      “backend”                  GtkPrintBackend *

Backend for the printer.

Flags: Read / Write / Construct Only

### The `“icon-name”` property

      “icon-name”                gchar *

The icon name to use for the printer.

Flags: Read

Default value: ""

### The `“is-virtual”` property

      “is-virtual”               gboolean

FALSE if this represents a real hardware printer.

Flags: Read / Write / Construct Only

Default value: FALSE

### The `“job-count”` property

      “job-count”                gint

Number of jobs queued in the printer.

Flags: Read

Allowed values: >= 0

Default value: 0

### The `“location”` property

      “location”                 gchar *

The location of the printer.

Flags: Read

Default value: ""

### The `“name”` property

      “name”                     gchar *

Name of the printer.

Flags: Read / Write / Construct Only

Default value: ""

### The `“paused”` property

      “paused”                   gboolean

This property is `TRUE` if this printer is paused. A paused printer still accepts jobs, but it does not print them.

Flags: Read

Default value: FALSE

Since 2.14

### The `“state-message”` property

      “state-message”            gchar *

String giving the current state of the printer.

Flags: Read

Default value: ""

## Signal Details

### The `“details-acquired”` signal

    void
    user_function (GtkPrinter *printer,
                   gboolean    success,
                   gpointer    user_data)

Gets emitted in response to a request for detailed information about a printer from the print backend. The `success` parameter indicates if the information was actually obtained.

#### Parameters

printer | the GtkPrinter on which the signal is emitted |
success | `TRUE` if the details were successfully acquired |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since 2.10