GtkPrinter

GtkPrinter — Represents a printer

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
char * icon-name Read
gboolean is-virtual Read / Write / Construct Only
int job-count Read
char * location Read
char * name Read / Write / Construct Only
gboolean paused Read
char * state-message Read

Signals

void details-acquired Run Last

Types and Values

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().

[closure]

Returns

TRUE to stop the enumeration, FALSE to continue

Since: 2.10


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.

Owner: GtkPrinter

Flags: Read

Default value: TRUE

Since: 2.14


The “accepts-pdf” property

  “accepts-pdf”              gboolean

TRUE if this printer can accept PDF.

Owner: GtkPrinter

Flags: Read / Write / Construct Only

Default value: FALSE


The “accepts-ps” property

  “accepts-ps”               gboolean

TRUE if this printer can accept PostScript.

Owner: GtkPrinter

Flags: Read / Write / Construct Only

Default value: TRUE


The “backend” property

  “backend”                  GtkPrintBackend *

Backend for the printer.

Owner: GtkPrinter

Flags: Read / Write / Construct Only


The “icon-name” property

  “icon-name”                char *

The icon name to use for the printer.

Owner: GtkPrinter

Flags: Read

Default value: ""


The “is-virtual” property

  “is-virtual”               gboolean

FALSE if this represents a real hardware printer.

Owner: GtkPrinter

Flags: Read / Write / Construct Only

Default value: FALSE


The “job-count” property

  “job-count”                int

Number of jobs queued in the printer.

Owner: GtkPrinter

Flags: Read

Allowed values: >= 0

Default value: 0


The “location” property

  “location”                 char *

The location of the printer.

Owner: GtkPrinter

Flags: Read

Default value: ""


The “name” property

  “name”                     char *

Name of the printer.

Owner: GtkPrinter

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.

Owner: GtkPrinter

Flags: Read

Default value: FALSE

Since: 2.14


The “state-message” property

  “state-message”            char *

String giving the current state of the printer.

Owner: GtkPrinter

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