GtkPrinter

GtkPrinter — Represents a printer

Synopsis

#include <gtk/gtk.h>

                    GtkPrinter;
                    GtkPrintBackend;
GtkPrinter *        gtk_printer_new                     (const gchar *name,
                                                         GtkPrintBackend *backend,
                                                         gboolean virtual_);
GtkPrintBackend *   gtk_printer_get_backend             (GtkPrinter *printer);
const gchar *       gtk_printer_get_name                (GtkPrinter *printer);
const gchar *       gtk_printer_get_state_message       (GtkPrinter *printer);
const gchar *       gtk_printer_get_description         (GtkPrinter *printer);
const gchar *       gtk_printer_get_location            (GtkPrinter *printer);
const gchar *       gtk_printer_get_icon_name           (GtkPrinter *printer);
gint                gtk_printer_get_job_count           (GtkPrinter *printer);
gboolean            gtk_printer_is_active               (GtkPrinter *printer);
gboolean            gtk_printer_is_paused               (GtkPrinter *printer);
gboolean            gtk_printer_is_accepting_jobs       (GtkPrinter *printer);
gboolean            gtk_printer_is_virtual              (GtkPrinter *printer);
gboolean            gtk_printer_is_default              (GtkPrinter *printer);
gboolean            gtk_printer_accepts_ps              (GtkPrinter *printer);
gboolean            gtk_printer_accepts_pdf             (GtkPrinter *printer);
GList *             gtk_printer_list_papers             (GtkPrinter *printer);
gint                gtk_printer_compare                 (GtkPrinter *a,
                                                         GtkPrinter *b);
gboolean            gtk_printer_has_details             (GtkPrinter *printer);
void                gtk_printer_request_details         (GtkPrinter *printer);
GtkPrintCapabilities  gtk_printer_get_capabilities      (GtkPrinter *printer);
GtkPageSetup *      gtk_printer_get_default_page_size   (GtkPrinter *printer);
gboolean            gtk_printer_get_hard_margins        (GtkPrinter *printer,
                                                         gdouble *top,
                                                         gdouble *bottom,
                                                         gdouble *left,
                                                         gdouble *right);
gboolean            (*GtkPrinterFunc)                   (GtkPrinter *printer,
                                                         gpointer data);
void                gtk_enumerate_printers              (GtkPrinterFunc func,
                                                         gpointer data,
                                                         GDestroyNotify destroy,
                                                         gboolean wait);

Object Hierarchy

  GObject
   +----GtkPrinter
  GObject
   +----GtkPrintBackend

Properties

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

Signals

  "details-acquired"                               : Run Last

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.

Details

GtkPrinter

typedef struct _GtkPrinter GtkPrinter;


GtkPrintBackend

typedef struct _GtkPrintBackend GtkPrintBackend;


gtk_printer_new ()

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

Creates a new GtkPrinter.

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.

printer :

a GtkPrinter

Returns :

the backend of printer

Since 2.10


gtk_printer_get_name ()

const gchar *       gtk_printer_get_name                (GtkPrinter *printer);

Returns the name of the printer.

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.

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.

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.

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.

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.

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

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.

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

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

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.

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.

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.

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

printer :

a GtkPrinter

Returns :

a newly allocated list of newly allocated GtkPageSetup s. . element-type GtkPageSetup. transfer full GtkPageSetup.

Since 2.12


gtk_printer_compare ()

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

Compares two printers.

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.

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.

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

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.

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

printer :

a GtkPrinter

top :

a location to store the top margin in

bottom :

a location to store the bottom margin in

left :

a location to store the left margin in

right :

a location to store the right margin in

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.

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.

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

Property Details

The "accepting-jobs" property

  "accepting-jobs"           gboolean              : Read

This property is TRUE if the printer is accepting jobs.

Default value: TRUE

Since 2.14


The "accepts-pdf" property

  "accepts-pdf"              gboolean              : Read / Write / Construct Only

TRUE if this printer can accept PDF.

Default value: TRUE


The "accepts-ps" property

  "accepts-ps"               gboolean              : Read / Write / Construct Only

TRUE if this printer can accept PostScript.

Default value: TRUE


The "backend" property

  "backend"                  GtkPrintBackend*      : Read / Write / Construct Only

Backend for the printer.


The "icon-name" property

  "icon-name"                gchar*                : Read

The icon name to use for the printer.

Default value: ""


The "is-virtual" property

  "is-virtual"               gboolean              : Read / Write / Construct Only

FALSE if this represents a real hardware printer.

Default value: FALSE


The "job-count" property

  "job-count"                gint                  : Read

Number of jobs queued in the printer.

Allowed values: >= 0

Default value: 0


The "location" property

  "location"                 gchar*                : Read

The location of the printer.

Default value: ""


The "name" property

  "name"                     gchar*                : Read / Write / Construct Only

Name of the printer.

Default value: ""


The "paused" property

  "paused"                   gboolean              : Read

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

Default value: FALSE

Since 2.14


The "state-message" property

  "state-message"            gchar*                : Read

String giving the current state of the printer.

Default value: ""

Signal Details

The "details-acquired" signal

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

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.

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.

Since 2.10