printer: Convert docs

This commit is contained in:
Matthias Clasen 2021-02-27 10:54:24 -05:00 committed by Emmanuele Bassi
parent 5225a0f253
commit eca14b763c
2 changed files with 190 additions and 117 deletions

View File

@ -29,18 +29,17 @@
#include "gtkprintjob.h"
/**
* SECTION:gtkprinter
* @Short_description: Represents a printer
* @Title: GtkPrinter
* GtkPrinter:
*
* A #GtkPrinter object represents a printer. You only need to
* deal directly with printers if you use the non-portable
* #GtkPrintUnixDialog API.
* A `GtkPrinter` object represents a printer.
*
* A #GtkPrinter allows to get status information about the printer,
* You only need to deal directly with printers if you use the
* non-portable [class@Gtk.PrintUnixDialog] 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.
* etc. Most importantly, a `GtkPrinter` object can be used to create
* a [class@Gtk.PrintJob] object, which lets you print to the printer.
*/
@ -113,6 +112,11 @@ gtk_printer_class_init (GtkPrinterClass *class)
object_class->set_property = gtk_printer_set_property;
object_class->get_property = gtk_printer_get_property;
/**
* GtkPrinter:name: (attributes org.gtk.Property.get=gtk_printer_get_name)
*
* The name of the printer.
*/
g_object_class_install_property (G_OBJECT_CLASS (class),
PROP_NAME,
g_param_spec_string ("name",
@ -120,6 +124,12 @@ gtk_printer_class_init (GtkPrinterClass *class)
P_("Name of the printer"),
"",
GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
/**
* GtkPrinter:backend: (attributes org.gtk.Property.get=gtk_printer_get_backend)
*
* The backend for the printer.
*/
g_object_class_install_property (G_OBJECT_CLASS (class),
PROP_BACKEND,
g_param_spec_object ("backend",
@ -127,6 +137,12 @@ gtk_printer_class_init (GtkPrinterClass *class)
P_("Backend for the printer"),
GTK_TYPE_PRINT_BACKEND,
GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
/**
* GtkPrinter:is-virtual: (attributes org.gtk.Property.get=gtk_printer_is_virtual)
*
* %FALSE if this represents a real hardware device.
*/
g_object_class_install_property (G_OBJECT_CLASS (class),
PROP_IS_VIRTUAL,
g_param_spec_boolean ("is-virtual",
@ -134,6 +150,12 @@ gtk_printer_class_init (GtkPrinterClass *class)
P_("FALSE if this represents a real hardware printer"),
FALSE,
GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
/**
* GtkPrinter:accepts-pdf: (attributes org.gtk.Property.get=gtk_printer_accepts_pdf)
*
* %TRUE if this printer can accept PDF.
*/
g_object_class_install_property (G_OBJECT_CLASS (class),
PROP_ACCEPTS_PDF,
g_param_spec_boolean ("accepts-pdf",
@ -141,6 +163,12 @@ gtk_printer_class_init (GtkPrinterClass *class)
P_("TRUE if this printer can accept PDF"),
FALSE,
GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
/**
* GtkPrinter:accepts-ps: (attributes org.gtk.Property.get=gtk_printer_accepts_ps)
*
* %TRUE if this printer can accept PostScript.
*/
g_object_class_install_property (G_OBJECT_CLASS (class),
PROP_ACCEPTS_PS,
g_param_spec_boolean ("accepts-ps",
@ -148,6 +176,12 @@ gtk_printer_class_init (GtkPrinterClass *class)
P_("TRUE if this printer can accept PostScript"),
TRUE,
GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
/**
* GtkPrinter:state-message: (attributes org.gtk.Property.get=gtk_printer_get_state_message)
*
* String giving the current status of the printer.
*/
g_object_class_install_property (G_OBJECT_CLASS (class),
PROP_STATE_MESSAGE,
g_param_spec_string ("state-message",
@ -155,6 +189,12 @@ gtk_printer_class_init (GtkPrinterClass *class)
P_("String giving the current state of the printer"),
"",
GTK_PARAM_READABLE));
/**
* GtkPrinter:location: (attributes org.gtk.Property.get=gtk_printer_get_location)
*
* Information about the location of the printer.
*/
g_object_class_install_property (G_OBJECT_CLASS (class),
PROP_LOCATION,
g_param_spec_string ("location",
@ -162,6 +202,12 @@ gtk_printer_class_init (GtkPrinterClass *class)
P_("The location of the printer"),
"",
GTK_PARAM_READABLE));
/**
* GtkPrinter:icon-name: (attributes org.gtk.Property.get=gtk_printer_get_icon_name)
*
* Icon name to use for the printer.
*/
g_object_class_install_property (G_OBJECT_CLASS (class),
PROP_ICON_NAME,
g_param_spec_string ("icon-name",
@ -169,6 +215,12 @@ gtk_printer_class_init (GtkPrinterClass *class)
P_("The icon name to use for the printer"),
"printer",
GTK_PARAM_READABLE));
/**
* GtkPrinter:job-count: (attributes org.gtk.Property.get=gtk_printer_get_job_count)
*
* Number of jobs queued in the printer.
*/
g_object_class_install_property (G_OBJECT_CLASS (class),
PROP_JOB_COUNT,
g_param_spec_int ("job-count",
@ -180,9 +232,10 @@ gtk_printer_class_init (GtkPrinterClass *class)
GTK_PARAM_READABLE));
/**
* GtkPrinter:paused:
* GtkPrinter:paused: (attributes org.gtk.Property.get=gtk_printer_is_paused)
*
* %TRUE if this printer is paused.
*
* This property is %TRUE if this printer is paused.
* A paused printer still accepts jobs, but it does
* not print them.
*/
@ -193,10 +246,11 @@ gtk_printer_class_init (GtkPrinterClass *class)
P_("TRUE if this printer is paused"),
FALSE,
GTK_PARAM_READABLE));
/**
* GtkPrinter:accepting-jobs:
* GtkPrinter:accepting-jobs: (attributes org.gtk.Property.get=gtk_printer_is_accepting_jobs)
*
* This property is %TRUE if the printer is accepting jobs.
* %TRUE if the printer is accepting jobs.
*/
g_object_class_install_property (G_OBJECT_CLASS (class),
PROP_ACCEPTING_JOBS,
@ -211,9 +265,11 @@ gtk_printer_class_init (GtkPrinterClass *class)
* @printer: the #GtkPrinter on which the signal is emitted
* @success: %TRUE if the details were successfully acquired
*
* 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.
* 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.
*/
signals[DETAILS_ACQUIRED] =
g_signal_new (I_("details-acquired"),
@ -367,13 +423,13 @@ gtk_printer_get_property (GObject *object,
/**
* gtk_printer_new:
* @name: the name of the printer
* @backend: a #GtkPrintBackend
* @backend: a `GtkPrintBackend`
* @virtual_: whether the printer is virtual
*
* Creates a new #GtkPrinter.
* Creates a new `GtkPrinter`.
*
* Returns: a new #GtkPrinter
**/
* Returns: a new `GtkPrinter`
*/
GtkPrinter *
gtk_printer_new (const char *name,
GtkPrintBackend *backend,
@ -391,8 +447,8 @@ gtk_printer_new (const char *name,
}
/**
* gtk_printer_get_backend:
* @printer: a #GtkPrinter
* gtk_printer_get_backend: (attributes org.gtk.Method.get_property=backend)
* @printer: a `GtkPrinter`
*
* Returns the backend of the printer.
*
@ -409,8 +465,8 @@ gtk_printer_get_backend (GtkPrinter *printer)
}
/**
* gtk_printer_get_name:
* @printer: a #GtkPrinter
* gtk_printer_get_name: (attributes org.gtk.Method.get_property=name)
* @printer: a `GtkPrinter`
*
* Returns the name of the printer.
*
@ -462,8 +518,8 @@ gtk_printer_set_description (GtkPrinter *printer,
}
/**
* gtk_printer_get_state_message:
* @printer: a #GtkPrinter
* gtk_printer_get_state_message: (attributes org.gtk.Method.get_property=state-message)
* @printer: a `GtkPrinter`
*
* Returns the state message describing the current state
* of the printer.
@ -499,8 +555,8 @@ gtk_printer_set_state_message (GtkPrinter *printer,
}
/**
* gtk_printer_get_location:
* @printer: a #GtkPrinter
* gtk_printer_get_location: (attributes org.gtk.Method.get_property=location)
* @printer: a `GtkPrinter`
*
* Returns a description of the location of the printer.
*
@ -535,8 +591,8 @@ gtk_printer_set_location (GtkPrinter *printer,
}
/**
* gtk_printer_get_icon_name:
* @printer: a #GtkPrinter
* gtk_printer_get_icon_name: (attributes org.gtk.Method.get_property=icon-name)
* @printer: a `GtkPrinter`
*
* Gets the name of the icon to use for the printer.
*
@ -566,8 +622,8 @@ gtk_printer_set_icon_name (GtkPrinter *printer,
}
/**
* gtk_printer_get_job_count:
* @printer: a #GtkPrinter
* gtk_printer_get_job_count: (attributes org.gtk.Method.get_property=job-count)
* @printer: a `GtkPrinter`
*
* Gets the number of jobs currently queued on the printer.
*
@ -603,7 +659,7 @@ gtk_printer_set_job_count (GtkPrinter *printer,
/**
* gtk_printer_has_details:
* @printer: a #GtkPrinter
* @printer: a `GtkPrinter`
*
* Returns whether the printer details are available.
*
@ -630,7 +686,7 @@ gtk_printer_set_has_details (GtkPrinter *printer,
/**
* gtk_printer_is_active:
* @printer: a #GtkPrinter
* @printer: a `GtkPrinter`
*
* Returns whether the printer is currently active (i.e.
* accepts new jobs).
@ -659,10 +715,11 @@ gtk_printer_set_is_active (GtkPrinter *printer,
}
/**
* gtk_printer_is_paused:
* @printer: a #GtkPrinter
* gtk_printer_is_paused: (attributes org.gtk.Method.get_property=paused)
* @printer: a `GtkPrinter`
*
* Returns whether the printer is currently paused.
*
* A paused printer still accepts jobs, but it is not
* printing them.
*
@ -695,8 +752,8 @@ gtk_printer_set_is_paused (GtkPrinter *printer,
}
/**
* gtk_printer_is_accepting_jobs:
* @printer: a #GtkPrinter
* gtk_printer_is_accepting_jobs: (attributes org.gtk.Method.get_property=accepting-jobs)
* @printer: a `GtkPrinter`
*
* Returns whether the printer is accepting jobs
*
@ -729,8 +786,8 @@ gtk_printer_set_is_accepting_jobs (GtkPrinter *printer,
}
/**
* gtk_printer_is_virtual:
* @printer: a #GtkPrinter
* gtk_printer_is_virtual: (attributes org.gtk.Method.get_property=is-virtual)
* @printer: a `GtkPrinter`
*
* Returns whether the printer is virtual (i.e. does not
* represent actual printer hardware, but something like
@ -749,8 +806,8 @@ gtk_printer_is_virtual (GtkPrinter *printer)
}
/**
* gtk_printer_accepts_pdf:
* @printer: a #GtkPrinter
* gtk_printer_accepts_pdf: (attributes org.gtk.Method.get_property=accepts-pdf)
* @printer: a `GtkPrinter`
*
* Returns whether the printer accepts input in
* PDF format.
@ -779,8 +836,8 @@ gtk_printer_set_accepts_pdf (GtkPrinter *printer,
}
/**
* gtk_printer_accepts_ps:
* @printer: a #GtkPrinter
* gtk_printer_accepts_ps: (attributes org.gtk.Method.get_property=accepts-ps)
* @printer: a `GtkPrinter`
*
* Returns whether the printer accepts input in
* PostScript format.
@ -832,7 +889,7 @@ gtk_printer_set_is_new (GtkPrinter *printer,
/**
* gtk_printer_is_default:
* @printer: a #GtkPrinter
* @printer: a `GtkPrinter`
*
* Returns whether the printer is the default printer.
*
@ -861,10 +918,13 @@ gtk_printer_set_is_default (GtkPrinter *printer,
/**
* gtk_printer_request_details:
* @printer: a #GtkPrinter
* @printer: a `GtkPrinter`
*
* Requests the printer details. When the details are available,
* the #GtkPrinter::details-acquired signal will be emitted on @printer.
* Requests the printer details.
*
* When the details are available, the
* [signal@Gtk.Printer::details-acquired] signal
* will be emitted on @printer.
*/
void
gtk_printer_request_details (GtkPrinter *printer)
@ -939,13 +999,16 @@ _gtk_printer_create_cairo_surface (GtkPrinter *printer,
/**
* gtk_printer_list_papers:
* @printer: a #GtkPrinter
* @printer: a `GtkPrinter`
*
* Lists all the paper sizes @printer supports.
* This will return and empty list unless the printers details are
* available, see gtk_printer_has_details() and gtk_printer_request_details().
*
* Returns: (element-type GtkPageSetup) (transfer full): a newly allocated list of newly allocated #GtkPageSetup s.
* This will return and empty list unless the printers details
* are available, see [method@Gtk.Printer.has_details] and
* [method@Gtk.Printer.request_details].
*
* Returns: (element-type GtkPageSetup) (transfer full): a newly
* allocated list of newly allocated `GtkPageSetup`s.
*/
GList *
gtk_printer_list_papers (GtkPrinter *printer)
@ -961,11 +1024,12 @@ gtk_printer_list_papers (GtkPrinter *printer)
/**
* gtk_printer_get_default_page_size:
* @printer: a #GtkPrinter
* @printer: a `GtkPrinter`
*
* Returns default page size of @printer.
*
* Returns: a newly allocated #GtkPageSetup with default page size of the printer.
* Returns: (transfer full): a newly allocated `GtkPageSetup` with default page size
* of the printer.
*/
GtkPageSetup *
gtk_printer_get_default_page_size (GtkPrinter *printer)
@ -976,22 +1040,26 @@ gtk_printer_get_default_page_size (GtkPrinter *printer)
g_return_val_if_fail (GTK_IS_PRINTER (printer), NULL);
backend_class = GTK_PRINT_BACKEND_GET_CLASS (priv->backend);
return backend_class->printer_get_default_page_size (printer);
}
/**
* gtk_printer_get_hard_margins:
* @printer: a #GtkPrinter
* @printer: a `GtkPrinter`
* @top: (out): a location to store the top margin in
* @bottom: (out): a location to store the bottom margin in
* @left: (out): a location to store the left margin in
* @right: (out): a location to store the right margin in
*
* 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.
* Retrieve the hard margins of @printer.
*
* Note: This will not succeed unless the printers details are available,
* see gtk_printer_has_details() and gtk_printer_request_details().
* These are 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 printers details are
* available, see [method@Gtk.Printer.has_details] and
* [method@Gtk.Printer.request_details].
*
* Returns: %TRUE iff the hard margins were retrieved
*/
@ -1010,19 +1078,21 @@ gtk_printer_get_hard_margins (GtkPrinter *printer,
/**
* gtk_printer_get_hard_margins_for_paper_size:
* @printer: a #GtkPrinter
* @paper_size: a #GtkPaperSize
* @printer: a `GtkPrinter`
* @paper_size: a `GtkPaperSize`
* @top: (out): a location to store the top margin in
* @bottom: (out): a location to store the bottom margin in
* @left: (out): a location to store the left margin in
* @right: (out): a location to store the right margin in
*
* 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.
* Retrieve the hard margins of @printer for @paper_size.
*
* Note: This will not succeed unless the printer's details are available,
* see gtk_printer_has_details() and gtk_printer_request_details().
* These are 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 printers details are
* available, see [method@Gtk.Printer.has_details] and
* [method@Gtk.Printer.request_details].
*
* Return value: %TRUE iff the hard margins were retrieved
*/
@ -1042,16 +1112,17 @@ gtk_printer_get_hard_margins_for_paper_size (GtkPrinter *printer,
/**
* gtk_printer_get_capabilities:
* @printer: a #GtkPrinter
* @printer: a `GtkPrinter`
*
* Returns the printers capabilities.
*
* This is useful when youre using #GtkPrintUnixDialogs manual-capabilities
* setting and need to know which settings the printer can handle and which
* you must handle yourself.
* This is useful when youre 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 printers details are available, see
* gtk_printer_has_details() and gtk_printer_request_details().
* This will return 0 unless the printers details are
* available, see [method@Gtk.Printer.has_details] and
* [method@Gtk.Printer.request_details].
*
* Returns: the printers capabilities
*/
@ -1069,8 +1140,8 @@ gtk_printer_get_capabilities (GtkPrinter *printer)
/**
* gtk_printer_compare:
* @a: a #GtkPrinter
* @b: another #GtkPrinter
* @a: a `GtkPrinter`
* @b: another `GtkPrinter`
*
* Compares two printers.
*
@ -1248,7 +1319,8 @@ list_printers_init (PrinterList *printer_list,
* @wait: if %TRUE, wait in a recursive mainloop until
* all printers are enumerated; otherwise return early
*
* Calls a function for all #GtkPrinters.
* Calls a function for all `GtkPrinter`s.
*
* If @func returns %TRUE, the enumeration is stopped.
*/
void

View File

@ -49,7 +49,7 @@ G_BEGIN_DECLS
* @GTK_PRINT_CAPABILITY_NUMBER_UP_LAYOUT: Print dialog will allow to rearrange
* pages when printing multiple pages per sheet
*
* An enum for specifying which features the print dialog should offer.
* Specifies which features the print dialog should offer.
*
* If neither %GTK_PRINT_CAPABILITY_GENERATE_PDF nor
* %GTK_PRINT_CAPABILITY_GENERATE_PS is specified, GTK assumes that all
@ -146,6 +146,7 @@ gboolean gtk_printer_get_hard_margins_for_paper_size (GtkPrinter
* @data: (closure): user data passed to gtk_enumerate_printers()
*
* 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.
*