Version 0.1
Lauris Kaplinski <lauris@ximian.com>

What is gnome-print?

Gnome-print is high-quality printing framework for GNOME.

What is there in gnome-print?

Gnome-print implements:

Is there a mailing list for gnome-print?

Yes, there is. You can acess both subscription/unsubscription and archives from web address: http://lists.ximian.com/mailman/listinfo/gnome-print The adress of list (for posting messages) is: gnome-print@ximian.com

I found a bug in gnome-print. How should I report it?

The best way is to use gnome bug tracking system (http://bugzilla.gnome.org/). Bugs entered there are never forgot by developers, as bugs reported by email often are. If reporting bug, be as exact as possible. Code examples are great. If reporting bugs related to PostScript printing, try to attach resulting PostScript file in addition to description, how your program produced it.

Which application use gnome-print?

The list is continuously growing. The best known ones are:

Does gnome-print use ghostscript? lpr? CUPS?

Current gnome-print relies entirely on underlying printing system for interfacing with actual printers. So it uses whatever libraries/prograsm your printing system use. In future it may implement direct drivers too, but of course, the general ones remain always present.

Why my application should use gnome-print? After all it is not so difficult to produce PostScript manually and doing so gives me endless possibilities.

The main role of gnome-print is standardization:

In general gnome-print tries to hide all complexity of different printing systems and printers, while presenting uniform easy-to-use and powerful-enough interface to application.

I want feature XYZ to be implemented!

First send a message to gnome-print mailing list. Maybe someone is already implementing it, or has better ideas how to solve your problem. Then you can file a 'WISHLIST' bug report, using bugzilla.gnome.org. If your idea has value for general audience, the chances for it to be implemented are good.

How I can help developing gnome-print library?

Send message to gnome-print list and we will contact you ;) While you do not need any permission to start hacking on gnome-print, it is usually better to ask first, whether your idea is already in work, or does somebody have better idea, how to implement that. If you think you have produced useful patch, send it to gnome-print mailing list, or directly to maintainers. The former is preferred, as maintainer may be sick, in vacation or buried alive under emails at moment, and then your valuable contribution will remain unnoticed.

How I can get gnome-print?

The easiest way is to use gnome binary distribution. Consult http://www.gnome.org/start/ about both how to get binaries and/or source for gnome packages. If you are using realatively modern GNU/Linux distribution chances are that gnome-print is already included in it. But as gnome-print is rapidly developing, you may want to check for updates.

How I can compile gnome-print from source tarball?

Just unpack tarball into separate directory. cd to gnome-print-X.Y directory and issue commands:

./configure --prefix=PREFIX
Become superuser
make install

Where prefix is your gnome installation prefix. If unsure, try gnome-config --prefix

What other libraries I need to compile gnome-print?

Generally you need working gnome installation. More specifically:

I have MY_LIBRARY installed, but gnome-print compilation says I have not!

If you have installed gnome from binary packages, make sure that you have installed corresponding development packages as well. If you have compiled MY_LIBRARY yourself, make sure that prefixes match.

How can I use gnome-print from my programs?

Unfortunately there is no good documentation about using gnome-print. The best way is probably to look into example code in tests directory in gnome-print source.

Can I use gnome-print from console programs?

Yes, you can. You still need X, Gtk+ and gnome to be installed, but X does not have to run on your machine. Of course, you cannot use print preview or printer selection widgets in that case. You also have to start your console program with gtk_type_init instead of gtk_init or gnome-init.

Which coordinate system does gnome-print use?

Gnome-print uses the same coordinate system as PostScript page description language. I.e. initially the 0,0 is at lower-left corner of page, x grows to right, y upwards and one unit corresponds to 1/72th of inch. You can change coordinate system using following methods:

  gnome_print_translate (pc, x, y)
  gnome_print_scale (pc, xscale, yscale)
  gnome_print_concat (pc, matrix)

If unsure, consult some textbook about computational geomtery. But in most cases you do not need anything other than translate and scale. Also, it is usually good idea to embed coordinate manipulation between gnome_print_gsave and gnome_print_grestore or you will soon loose track, which coordinate system is in use at any given moment.

I want to print! How I can get that GnomePrintContext?

Either use

  printer = gnome_printer_new_generic_ps (filename)
  pc = gnome_print_context_new_with_paper_size [con't...]
       (printer, "PAPER_NAME")

It works for console, but does not allow you to choose driver (but in most cases you want PostScript anyways).

  printer = gnome_printer_dialog_new_modal ()
  pc = gnome_print_context_new_with_paper_size [con't...]
       (printer, "PAPER_NAME")

It works only from X, but presents user with printer selection dialog. Instead of dialog, you can use printer selection widget and embed it into your own page setup widget, consult gnome_printer_dialog.h for more information.

Can I send output to pipe? To program as file argument?

Yes, you can. Use '|program' as output file name to pipe otuput to program Use '*program' as output file name to send output to file and execute program with file name as argument.

How can I get that nice print preview?

Use GnomePrintMaster and GnomePrintMasterPreview:

gpm = gnome_print_master_new ()
pc = gnome_print_master_get_context (gpm)
gpmp = gnome_print_master_preview_new (gpm, "title");
gnome_print_master_close (gpm);

How do I draw line in gnome-print?

gnome_print_newpath (pc)
gnome_print_moveto (pc, x0, y0)
gnome_print_lineto (pc, x1, y1)
gnome_print_stroke (pc)

You may, of course, want to specify graphic settings, like color, line width and so on.

Is gnome-print methods identical to PostScript operators?

No, they are not. Most important differences are:

Bitmap images look bad on printout, but everything seems fine in preview!

Most probably you are using bitmaps with alpha channel. As PostScript cannot print semitransparent images, all bitmaps with alpha are rendered into temporary buffer and later sent to printer as RGB bitmaps. That method has currently (version 0.28) hardcoded resolution of 72dpi.

Please note, that your image does not have to use any transparency - just having a channel is enough to force intermediate rendering. If you are using gdk-pixbuf to read images, try either changing file format to png without alpha or jpeg, or reconde images manually to RGB. Some file formats are always loaded with alpha channel by gdk-pixbuf.

Everything prints except bitmap images. Should I file bug report?

Make sure that you set up correct transformation matrix before printing bitmaps. Gnome-print uses PostScript convention to scale all bitmaps to (0,0 - 1,1) square in user coordinates. So if you do not set coordinate system, your image will be printed as tiny dot in lower-left corner of page (and usually falls into printers unprintable area). The correct way to print unscaled upright image is:

gnome_print_gsave (pc)
gnome_print_translate (pc, image_left_x, image_bottom_y)
gnome_print_scale (pc, image_width, image_height)
gnome_print_{rgb|rgba|gray}image [con't...]
   (pc, pixels, width, height, rowstride)
gnome_print_grestore (pc)

Can gnome-print use TrueType fonts?

At moment (version 0.28) unfortunately not. This is much asked feature and will be present in next version of gnome-print.

How I can add fonts to gnome-print?

It depends of your gnome-print version. Up to version 0.26 you have to manually add these to fontmap file (found at PREFIX/fonts). Starting from version 0.27 you can use program gnome-font-install. Just run it, giving the directory(ies) with your font files (pfb and afm) as argument, and send output to either PREFIX/fontmap2 or ~/.gnome/fonts/fontmap.

Which text encoding gnome-print uses?

Some legacy code aside, gnome-print uses strictly utf-8 text encoding.

Character metrics are not calculated correctly!

Please note, that several methods use glyph, not character value. Glyphs are actual printable shapes, as opposed to characters, that are language units - so single glyph may represent many characters (ligatures) or single character may be represented by several glyphs. Glyphs are font-dependent.

So, how can you find, which glyph corresponds to given character?

If your typographic needs are modest, you can use gnome_font_face_lookup_default (face, character) For advanced typography you have to use afm files directly, and extract necessary information from glyph names.

My russian Type1 fonts print well from almost any applications, but not from the ones using gnome-print!

Make sure, that your fonts use afiiXYZQ names for cyrillic glyphs. Some russian fonts use latin1 glyph names (like Aacute, otilde) for cyrillic glyphs, so supposed latin1 encoding becomes actually KOI8 or some similar cyrillic encoding. Gnome-print uses unicode internally and reencodes all fonts to private encoding, so it cannot be so easily fooled. As it does not find any cyrillic glyph names in font description, it supposes that given font cannot output cyrillic text.

How can I output formatted text in gnome-print?

You have to use glyphlist interface.

What is glyphlist?

Glyphlist is intermediate text format, used by gnome-print to generate identical text display on all output devices. Glyphlist uses font-specific glyphs instead of characters, so there is no ambiguity in actual text formatting (whether to use fi ligature, whether to use swashes etc.), but can preserve actual text flow (i.e. you give starting position and series of glyphs, instead of specifying the position of every glyph manually). Of course, if you need more complex placement (like typesetting 'TeX' ;), you can specify glyph positions manually too. In addition to that you can switch fonts and colors, and for flowing glyphs specify the amount of kerning and letterspacing.

What are GnomeFontFace, GnomeFont, GnomeRFont

GnomeFontFace is unscaled typeface. I.e. all metrics are specified as of the font with 1000x1000 em square. GnomeFontFace implements the actual font file parsing code, so character-glyph mapping is done on it.

GnomeFont is typeface scaled to master output device and requested font size. I.e. 12pt Helvetica GnomeFont metrics correspond to 12x12 em square. Or by other words - GnomeFont is font scaled to gnome-print base coordinate system units.

GnomeRFont is instance of GnomeFont, adjusted for printing on certain raster device with resolution that can be quite different from gnome-print base coordinate system. For example, 12pt Helvetica GnomeRFont for 720x720dpi printer metrics correspond to 120x120 em square.

Why that font complexity? Wouldn't it be easier to use just single font class?

We have tried to resolve unavoidable grid-aligning problem. I.e. for actual printing font metrics are usually scaled to integer values in given device grid (resolution). So if you try to print long line of glyphs on different devices, either:

So the idea is to have GnomeFont, that is adjusted to master output device (for example typesetter), and for every actual output device we generate different GnomeRFont. If actual output device == master output device, the metrics of GnomeFont and GnomeRFont are identical (if multiplied by resolution difference), for any other they differ a little. Using glyphlists you can choose best strategy to minimise visual distortions for your application.

What about CMYK colorspace?

We want it too. Hopefully in some near future version of gnome-print. Unfortunately it is area picked with patents, so probably we cannot give top-of-the-industry solution here.

It would be cool to have printing interface on canvas items!

It is not so cool at all. In model-view-controller context both current gnome-canvas and gnome-print-context implement single view. Adding subview (printing interface) to existing view (canvas) is not very good idea.

What would be cool is either: