libgnomeprint status/usage

[Lauris Kaplinski <lauris ximian com>]

Hello!

After scanning all public headers of libggnomeprint, I got feeling
that the absolute base is really there, and should be usable by
applications as-is. Except maybe pango<->gnomeprint mappings, about
which I do not have idea, and have to rely on wishes/suggestions
of application porters.

Anyways, what follows is the suggested usage pattern of libgnomeprint
for all of you application porters there:

There are no more such things as printers and profiles, instead
almost every setting is stored in single opaque megaobject 
GnomePrintConfig.

1. Get GnomePrintConfig

  cfg = gnome_print_config_default ()

You may want to keep that around all the time program is running,
to keep settings. There is currently no way to load/save config
per-program.

2. Once you have config object, you can do several things:

2.1. Read/set values manually, using GnomePrintConfig get/set
methods. There are some convenience ones to modify/read values of
known type too.

2.2. Create libgnomeui config widgets/dialogs, attaching those
to config object.

2.3. Generate GnomePrintMaster and do previewing/printing.

The order is really not important, other than at moment notification
system is diabled - i.e. config dialogs do not update themselves, if
you change values manually. So better make your dialogs modal by now, 
and destroy them after use instead of just hiding.

If you want print-preview, the logical object is GnomePrintMasterPreview
from libgnomeprintui, that requires GnomePrintMaster to be created
beforehand.

Automatic layouts and multiple copies are handled by GnomePrintMaster,
creating print context by hand sends your job to printer completely
as-is.


About layouts and page size

libgnomeprint can do some automatic layouting for you. But do not think,
it can replace multiple column support in word processor - it is
not meant for such things.
Automatic layout functionality is constrained to:
a) setting print orientation to whatever direction you feed paper
   into printer (it is really usable for envelopes)
b) specifying portrait/landscape modes
c) fitting multiple pages to single sheet of paper, either by scaling,
   or by subdivinding printable area (so you can do labels and business
   cards easily)

For (b) and (c) it needs some slight application support. Namely,
printable area size may not be identical to paper size (in case of
landscape mode width/height are swapped, in case of unscaled subdivision
either or both are smaller). So application should not use paper size
values stored in GnomePrintContext (or stored by htemselves), but 
instead let libgnomeprint to calculate available imaging area size:

gnome_print_master_get_page_size_from_config (cfg, &width, &height)

It has weird name, but I kept it in print master header to make it 
clear, that those values will ony be correct, if printing will be done
via print master. If user creates contexts directly, plain paper
values are used.


Example usage pattern:

GnomePrintConfig *cfg;
GnomePrintContext *ctx;
gint response;

cfg = gnome_print_config_default ();
dlg = gnome_print_dialog_new (cfg); /* libgnomeprintui method */
response = gtk_dialog_run (dlg)
if (response != GNOME_PRINT_DIALOG_RESPONSE_CANCEL) {
  gdouble width, height;
  gnome_print_master_get_page_size_from_config (cfg, &width, &height);
  master = gnome_print_master_new_from_config (cfg);
  ctx = gnome_print_master_get_context (master);
    /* Do page rendering, using width and height retrieved */
  g_object_unref (G_OBJECT (ctx));
  gnome_print_master_close (master);
  if (response == GNOME_PRINT_DIALOG_RESPONSE_PREVIEW) {
    GtkWidget *p;
    p = gnome_print_master_preview_new (master, "Title goes here");
    gtk_widget_show (p);
      /* Connect signals etc. and run gtk_main () */
  } else {
    gnome_print_master_print (master);
}
g_object_unref (G_OBJECT (master));

/* Thats all (written by heart - cannot guarantee it compiles) */


About some more values stored in GnomePrintContext

GnomePrintContext has keys for both physical and logical margins. 
Physical ones cannot be modified, so they there are just FYI. Logical
ones are settable. You can use it for storing user selected margins for
your program, but you do not have to. Just, if you want
GnomepaperSelector widget to display correct margins, make sure you
set those in GnomePrintConfig before creating it.

Paper size is read-only for predefined papers. But 'Custom' paper
has read-write size keys. Just do not forget, that paper size !=
available area in some cases.

If you want to set portrait/landscape modes by hand, the corresponding
values are "R0" and "R90"
To set identity layout (i.e. no multipages), use value "Plain".


I know, that in some cases all this is evil, so maybe I should add some
flags/methods for application to signal, whehter they allow multipage
layouts etc. Maybe not.


Best wishes,
Lauris Kaplinski