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

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


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]


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


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


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


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


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


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


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


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


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


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


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


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


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


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]


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


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


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

 

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


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.


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


gtk_printer_get_hard_margins_for_paper_size ()

gboolean
gtk_printer_get_hard_margins_for_paper_size
                               (GtkPrinter *printer,
                                GtkPaperSize *paper_size,
                                gdouble *top,
                                gdouble *bottom,
                                gdouble *left,
                                gdouble *right);

Retrieve the hard margins of printer for paper_size , 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

 

paper_size

a GtkPaperSize

 

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


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


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

 

Types and Values

GtkPrinter

typedef struct _GtkPrinter 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


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”                gchar *

The icon name to use for the printer.

Owner: GtkPrinter

Flags: Read

Default value: "printer"


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”                gint

Number of jobs queued in the printer.

Owner: GtkPrinter

Flags: Read

Allowed values: >= 0

Default value: 0


The “location” property

  “location”                 gchar *

The location of the printer.

Owner: GtkPrinter

Flags: Read

Default value: ""


The “name” property

  “name”                     gchar *

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


The “state-message” property

  “state-message”            gchar *

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