CtkPrintJob: CTK+ 3 Reference Manual

CtkPrintJob

CtkPrintJob — Represents a print job

Functions

void	(*CtkPrintJobCompleteFunc) ()
CtkPrintJob *	ctk_print_job_new ()
CtkPrintSettings *	ctk_print_job_get_settings ()
CtkPrinter *	ctk_print_job_get_printer ()
const gchar *	ctk_print_job_get_title ()
CtkPrintStatus	ctk_print_job_get_status ()
gboolean	ctk_print_job_set_source_fd ()
gboolean	ctk_print_job_set_source_file ()
cairo_surface_t *	ctk_print_job_get_surface ()
void	ctk_print_job_send ()
void	ctk_print_job_set_track_print_status ()
gboolean	ctk_print_job_get_track_print_status ()
CtkPrintPages	ctk_print_job_get_pages ()
void	ctk_print_job_set_pages ()
CtkPageRange *	ctk_print_job_get_page_ranges ()
void	ctk_print_job_set_page_ranges ()
CtkPageSet	ctk_print_job_get_page_set ()
void	ctk_print_job_set_page_set ()
gint	ctk_print_job_get_num_copies ()
void	ctk_print_job_set_num_copies ()
gdouble	ctk_print_job_get_scale ()
void	ctk_print_job_set_scale ()
guint	ctk_print_job_get_n_up ()
void	ctk_print_job_set_n_up ()
CtkNumberUpLayout	ctk_print_job_get_n_up_layout ()
void	ctk_print_job_set_n_up_layout ()
gboolean	ctk_print_job_get_rotate ()
void	ctk_print_job_set_rotate ()
gboolean	ctk_print_job_get_collate ()
void	ctk_print_job_set_collate ()
gboolean	ctk_print_job_get_reverse ()
void	ctk_print_job_set_reverse ()

Properties

CtkPageSetup *	page-setup	Read / Write / Construct Only
CtkPrinter *	printer	Read / Write / Construct Only
CtkPrintSettings *	settings	Read / Write / Construct Only
char *	title	Read / Write / Construct Only
gboolean	track-print-status	Read / Write

Signals

void

status-changed

Run Last

Types and Values

struct

CtkPrintJob

Object Hierarchy

    GObject
    ╰── CtkPrintJob

Includes

#include <ctk/ctkunixprint.h>

Description

A CtkPrintJob object represents a job that is sent to a printer. You only need to deal directly with print jobs if you use the non-portable CtkPrintUnixDialog API.

Use ctk_print_job_get_surface() to obtain the cairo surface onto which the pages must be drawn. Use ctk_print_job_send() to send the finished job to the printer. If you don’t use cairo CtkPrintJob also supports printing of manually generated postscript, via ctk_print_job_set_source_file().

Functions

CtkPrintJobCompleteFunc ()

void
(*CtkPrintJobCompleteFunc) (CtkPrintJob *print_job,
                            gpointer user_data,
                            const GError *error);

The type of callback that is passed to ctk_print_job_send(). It is called when the print job has been completely sent.

Parameters

print_job	the CtkPrintJob
user_data	user data that has been passed to `ctk_print_job_send()`
error	a GError that contains error information if the sending of the print job failed, otherwise `NULL`

ctk_print_job_new ()

CtkPrintJob *
ctk_print_job_new (const gchar *title,
                   CtkPrinter *printer,
                   CtkPrintSettings *settings,
                   CtkPageSetup *page_setup);

Creates a new CtkPrintJob.

Parameters

title	the job title
printer	a CtkPrinter
settings	a CtkPrintSettings
page_setup	a CtkPageSetup

Returns

a new CtkPrintJob

Since: 2.10

ctk_print_job_get_settings ()

CtkPrintSettings *
ctk_print_job_get_settings (CtkPrintJob *job);

Gets the CtkPrintSettings of the print job.

Parameters

job

a CtkPrintJob

Returns

the settings of job .

[transfer none]

Since: 2.10

ctk_print_job_get_printer ()

CtkPrinter *
ctk_print_job_get_printer (CtkPrintJob *job);

Gets the CtkPrinter of the print job.

Parameters

job

a CtkPrintJob

Returns

the printer of job .

[transfer none]

Since: 2.10

ctk_print_job_get_title ()

const gchar *
ctk_print_job_get_title (CtkPrintJob *job);

Gets the job title.

Parameters

job

a CtkPrintJob

Returns

the title of job

Since: 2.10

ctk_print_job_get_status ()

CtkPrintStatus
ctk_print_job_get_status (CtkPrintJob *job);

Gets the status of the print job.

Parameters

job

a CtkPrintJob

Returns

the status of job

Since: 2.10

ctk_print_job_set_source_fd ()

gboolean
ctk_print_job_set_source_fd (CtkPrintJob *job,
                             int fd,
                             GError **error);

Make the CtkPrintJob send an existing document to the printing system. The file can be in any format understood by the platforms printing system (typically PostScript, but on many platforms PDF may work too). See ctk_printer_accepts_pdf() and ctk_printer_accepts_ps().

This is similar to ctk_print_job_set_source_file(), but takes expects an open file descriptor for the file, instead of a filename.

Parameters

job	a CtkPrintJob
fd	a file descriptor
error	return location for errors

Returns

FALSE if an error occurred

Since: 3.22

ctk_print_job_set_source_file ()

gboolean
ctk_print_job_set_source_file (CtkPrintJob *job,
                               const gchar *filename,
                               GError **error);

Parameters

job	a CtkPrintJob
filename	the file to be printed.	[type filename]
error	return location for errors

Returns

FALSE if an error occurred

Since: 2.10

ctk_print_job_get_surface ()

cairo_surface_t *
ctk_print_job_get_surface (CtkPrintJob *job,
                           GError **error);

Gets a cairo surface onto which the pages of the print job should be rendered.

Parameters

job	a CtkPrintJob
error	return location for errors, or `NULL`.	[allow-none]

Returns

the cairo surface of job .

[transfer none]

Since: 2.10

ctk_print_job_send ()

void
ctk_print_job_send (CtkPrintJob *job,
                    CtkPrintJobCompleteFunc callback,
                    gpointer user_data,
                    GDestroyNotify dnotify);

Sends the print job off to the printer.

Parameters

job	a CtkPrintJob
callback	function to call when the job completes or an error occurs
user_data	user data that gets passed to `callback`
dnotify	destroy notify for `user_data`

Since: 2.10

ctk_print_job_set_track_print_status ()

void
ctk_print_job_set_track_print_status (CtkPrintJob *job,
                                      gboolean track_status);

If track_status is TRUE, the print job 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.

Parameters

job	a CtkPrintJob
track_status	`TRUE` to track status after printing

Since: 2.10

ctk_print_job_get_track_print_status ()

gboolean
ctk_print_job_get_track_print_status (CtkPrintJob *job);

Returns wheter jobs will be tracked after printing. For details, see ctk_print_job_set_track_print_status().

Parameters

job

a CtkPrintJob

Returns

TRUE if print job status will be reported after printing

Since: 2.10

ctk_print_job_get_pages ()

CtkPrintPages
ctk_print_job_get_pages (CtkPrintJob *job);

Gets the CtkPrintPages setting for this job.

Parameters

job

a CtkPrintJob

Returns

the CtkPrintPages setting

Since: 3.0

ctk_print_job_set_pages ()

void
ctk_print_job_set_pages (CtkPrintJob *job,
                         CtkPrintPages pages);

Sets the CtkPrintPages setting for this job.

Parameters

job	a CtkPrintJob
pages	the CtkPrintPages setting

Since: 3.0

ctk_print_job_get_page_ranges ()

CtkPageRange *
ctk_print_job_get_page_ranges (CtkPrintJob *job,
                               gint *n_ranges);

Gets the page ranges for this job.

Parameters

job	a CtkPrintJob
n_ranges	return location for the number of ranges.	[out]

Returns

a pointer to an array of CtkPageRange structs.

[array length=n_ranges][transfer none]

Since: 3.0

ctk_print_job_set_page_ranges ()

void
ctk_print_job_set_page_ranges (CtkPrintJob *job,
                               CtkPageRange *ranges,
                               gint n_ranges);

Sets the page ranges for this job.

Parameters

job	a CtkPrintJob
ranges	pointer to an array of CtkPageRange structs.	[array length=n_ranges][transfer full]
n_ranges	the length of the `ranges` array

Since: 3.0

ctk_print_job_get_page_set ()

CtkPageSet
ctk_print_job_get_page_set (CtkPrintJob *job);

Gets the CtkPageSet setting for this job.

Parameters

job

a CtkPrintJob

Returns

the CtkPageSet setting

Since: 3.0

ctk_print_job_set_page_set ()

void
ctk_print_job_set_page_set (CtkPrintJob *job,
                            CtkPageSet page_set);

Sets the CtkPageSet setting for this job.

Parameters

job	a CtkPrintJob
page_set	a CtkPageSet setting

Since: 3.0

ctk_print_job_get_num_copies ()

gint
ctk_print_job_get_num_copies (CtkPrintJob *job);

Gets the number of copies of this job.

Parameters

job

a CtkPrintJob

Returns

the number of copies

Since: 3.0

ctk_print_job_set_num_copies ()

void
ctk_print_job_set_num_copies (CtkPrintJob *job,
                              gint num_copies);

Sets the number of copies for this job.

Parameters

job	a CtkPrintJob
num_copies	the number of copies

Since: 3.0

ctk_print_job_get_scale ()

gdouble
ctk_print_job_get_scale (CtkPrintJob *job);

Gets the scale for this job (where 1.0 means unscaled).

Parameters

job

a CtkPrintJob

Returns

the scale

Since: 3.0

ctk_print_job_set_scale ()

void
ctk_print_job_set_scale (CtkPrintJob *job,
                         gdouble scale);

Sets the scale for this job (where 1.0 means unscaled).

Parameters

job	a CtkPrintJob
scale	the scale

Since: 3.0

ctk_print_job_get_n_up ()

guint
ctk_print_job_get_n_up (CtkPrintJob *job);

Gets the n-up setting for this job.

Parameters

job

a CtkPrintJob

Returns

the n-up setting

Since: 3.0

ctk_print_job_set_n_up ()

void
ctk_print_job_set_n_up (CtkPrintJob *job,
                        guint n_up);

Sets the n-up setting for this job.

Parameters

job	a CtkPrintJob
n_up	the n-up value

Since: 3.0

ctk_print_job_get_n_up_layout ()

CtkNumberUpLayout
ctk_print_job_get_n_up_layout (CtkPrintJob *job);

Gets the n-up layout setting for this job.

Parameters

job

a CtkPrintJob

Returns

the n-up layout

Since: 3.0

ctk_print_job_set_n_up_layout ()

void
ctk_print_job_set_n_up_layout (CtkPrintJob *job,
                               CtkNumberUpLayout layout);

Sets the n-up layout setting for this job.

Parameters

job	a CtkPrintJob
layout	the n-up layout setting

Since: 3.0

ctk_print_job_get_rotate ()

gboolean
ctk_print_job_get_rotate (CtkPrintJob *job);

Gets whether the job is printed rotated.

Parameters

job

a CtkPrintJob

Returns

whether the job is printed rotated

Since: 3.0

ctk_print_job_set_rotate ()

void
ctk_print_job_set_rotate (CtkPrintJob *job,
                          gboolean rotate);

Sets whether this job is printed rotated.

Parameters

job	a CtkPrintJob
rotate	whether to print rotated

Since: 3.0

ctk_print_job_get_collate ()

gboolean
ctk_print_job_get_collate (CtkPrintJob *job);

Gets whether this job is printed collated.

Parameters

job

a CtkPrintJob

Returns

whether the job is printed collated

Since: 3.0

ctk_print_job_set_collate ()

void
ctk_print_job_set_collate (CtkPrintJob *job,
                           gboolean collate);

Sets whether this job is printed collated.

Parameters

job	a CtkPrintJob
collate	whether the job is printed collated

Since: 3.0

ctk_print_job_get_reverse ()

gboolean
ctk_print_job_get_reverse (CtkPrintJob *job);

Gets whether this job is printed reversed.

Parameters

job

a CtkPrintJob

Returns

whether the job is printed reversed.

Since: 3.0

ctk_print_job_set_reverse ()

void
ctk_print_job_set_reverse (CtkPrintJob *job,
                           gboolean reverse);

Sets whether this job is printed reversed.

Parameters

job	a CtkPrintJob
reverse	whether the job is printed reversed

Since: 3.0

Types and Values

struct CtkPrintJob

struct CtkPrintJob;

Property Details

The `“page-setup”` property

  “page-setup”               CtkPageSetup *

Page Setup.

Owner: CtkPrintJob

Flags: Read / Write / Construct Only

The `“printer”` property

  “printer”                  CtkPrinter *

Printer to print the job to.

Owner: CtkPrintJob

Flags: Read / Write / Construct Only

The `“settings”` property

  “settings”                 CtkPrintSettings *

Printer settings.

Owner: CtkPrintJob

Flags: Read / Write / Construct Only

The `“title”` property

  “title”                    char *

Title of the print job.

Owner: CtkPrintJob

Flags: Read / Write / Construct Only

Default value: NULL

The `“track-print-status”` property

  “track-print-status”       gboolean

TRUE if the print job will continue to emit status-changed signals after the print data has been sent to the printer or print server.

Owner: CtkPrintJob

Flags: Read / Write

Default value: FALSE

Signal Details

The `“status-changed”` signal

void
user_function (CtkPrintJob *job,
               gpointer     user_data)

Gets emitted when the status of a job changes. The signal handler can use ctk_print_job_get_status() to obtain the new status.

Parameters

job	the CtkPrintJob object on which the signal was emitted
user_data	user data set when the signal handler was connected.

Flags: Run Last

Since: 2.10