GtkPrinter

Pretty much just an opaque object

GList *      gtk_printer_list_available (void);
GtkPrinter  *gtk_printer_find           (const gchar *name);

const gchar *gtk_printer_get_name       (GtkPrinter  *printer);

/* Does things like compute minimum margins */
void         gtk_printer_recompute_settings (GtkPrinter       *printer,
                                             GtkPrintSettings *settings);

lutz@gnome.org: Settings should be updated automatically IMHO. I don't like the fact that all settings are treated the same. There are settings for

1. destination
   • printers (PPD-files, includes duplex, paper size, minimum margins...)
   • files (location)
   • email (address, subject, body...)
2. driver

   • PostScript (level...)

   • PDF (version...)
   • SVG/PNG/...
3. page (page size, layout like landscape/portrait/nup..., margins, selection/order like "1-4,6"/reverse/even...)
4. content (like printing line numbers, formulas...)

I'd create objects for 1-3 (GPrintDestination, GPrintDriver, GPrintPage) and leave it up to the application to handle 4. 1 and 2 (GtkPrintDialog, see below) are independent from the document. 3 and 4 are directly connected to the document (GtkPageDialog, see below) and should be accessible through the "Print setup..." menu item.

GtkPrintSettings

A bag of named values. Printer is a special property, and not one of these values:

void        gtk_print_settings_set_printer (GtkPrintDialog   *dialog,
                                            GtkPrinter       *printer);
GtkPrinter *gtk_print_settings_get_printer (GtkPrintSettings *settings);

lutz@gnome.org: Why GtkPrintDialog? Shouldn't that be GtkPrintSettings?

The printer specific (and thus necessarily extensible) parts of this could be done various different way.

One way would be a strict bag of GValues:

void gtk_print_settings_set_value (GtkPrintSettings *settings,
                                   gchar            *name,
                                   const GValue     *value);
void gtk_print_settings_get_value (GtkPrintSettings *settings,
                                   gchar            *name,
                                   GValue           *value);

This is very extensible (just make up a name), but isn't a real API, and we can't do g_object_set_/get().

Or we could have ways of registering properties (for print backends, wouldn't have to be public)

void gtk_print_settings_install_property (GtkPrintSettings    *settings,
                                          gchar               *name,
                                          GtkParamSpec        *pspec);

That would allow g_object_set()/get(). We might want to have real API for more commonly set/get stuff:

void gtk_print_settings_set_paper_size (GtkPrintSettings *settings,
                                        gdouble           width,
                                        gdouble           height);
void gtk_print_settings_get_paper_size (GtkPrintSettings *settings,
                                        gdouble          *width,
                                        gdouble          *height);

void                gtk_print_settings_set_orientation (GtkPrintSettings   *settings,
                                                        GtkPrintOrientation orientation);
GtkPrintOrientation gtk_print_settings_get_orientation (GtkPrintSettings   *settings);

There are also values that you want to get, but aren't something an app can set (see gtk_printer_recompute_settings() above)

void gtk_print_settings_get_minimum_margins (GtkPrintSettings *settings,
                                             gdouble          *left,
                                             gdouble          *right,
                                             gdouble          *top,
                                             gdouble          *bottom);

GtkPageDialog

A standard margins-and-orientation dialog

typedef struct _GtkPageDialog GtkPageDialog;

struct _GtkPageDialogClass
{
  void (*result)          (GtkPrintDialog *dialog,
                           gint            response_id);
};

void gtk_page_dialog_new (GtkPageSettings *settings);

gint gtk_page_dialog_run      (GtkPageDialog *dialog);
void gtk_page_dialog_run_aync (GtkPageDialog *dialog);

/* Returns the GtkPrintSettings maintained by the dialog; same as
 * passed to new()
 */
GtkPrintSettings *gtk_page_dialog_get_settings (GtkPageDialog *dialog);

lutz@gnome.org: This shouldn't be a GtkDialog. It should be a widget that can be embedded in the "Print setup" dialog that may contain many more settings (like if line numbers should be printed).

GtkPrintDialog

The main UI for the user to select a printer and printer-specific options.

typedef struct _GtkPrintDialog GtkPrintDialog;

struct _GtkPrintDialogClass
{
  void (*printer_changed) (GtkPrintDialog *dialog);
  void (*result)          (GtkPrintDialog *dialog,
                           gint            response_id);
};

void gtk_print_dialog_new (void);

gint gtk_print_dialog_run      (GtkPrintDialog *dialog);
void gtk_print_dialog_run_aync (GtkPrintDialog *dialog);

/* Returns the GtkPrintSettings maintained by the dialog; same as
 * passed to new()
 */
GtkPrintSettings *gtk_print_dialog_get_settings (GtkPrintDialog *dialog);

lutz@gnome.org: GtkPrintSettings should be a standard property. Then, the gtk_print_dialog_get_settings is not needed. And you can load settings using g_object_set. And the printer_changed signal is not necessary (should be emitted by the settings). If the GtkPrintDialog is derived from GtkDialog, you don't need the reponse signal either. Nor gtk_print_dialog_run.

GtkPrintJob

Once you have your GtkPrintSettings, you can use it to create a job then draw to the job with cairo.

GtkPrintJob *gtk_print_job_new          (GtkPrintSettings *settings);

cairo_surface_t *gtk_print_job_get_surface  (GtkPrintJob *job);

/* cairo_create (Gtk_print_job_get_surface (job)) */
cairo_t *        gtk_print_job_create_cairo (GtkPrintJob *job);

/* Send the job to the printer */
void         gtk_print_job_end          (GtkPrintJob *job);