EuGTK Printing

EuGTK 4.12.0

GtkPrinter support functions

Introduction

This include adds very easy-to-use printing capabilities to EuGTK; most printing tasks require only one or two extra lines of code.

It offers the ability to print documents on physical printers as well as to print them as .pdf or .ps (postscript), and perhaps .svg files, depending upon the hardware and software installed on your pc.

Setup

When printing, font size, lines-per-page, and page length must be taken into account. Obviously, the larger the font, the fewer lines will fit on a given page.

By default (on Linux), GtkPrinter.e will print using an Ubuntu Mono 8pt. font and print 62 lines per 8.5x11 inch (na_letter) page or 84 lines on 8.5x14 (na_legal) paper. Other paper sizes and orientations are available from the pop-up printer dialog, and these should also be computed automatically, as long as the font isn't changed. Try test190.

Other fonts may not work so well with the default lines_per_page settings. They often take up more (or less) space, both vertically and horizontally, than the same size Ubuntu Mono font. For these, you must set lines_per_page manually.

Example 1:

        printer:font = "Ubuntu mono 10"
        printer:lines_per_page = 65

Example 2:

      
        printer:font = "Purisa 12"
        printer:lines_per_page = 34

Some options, like the paper size and orientation, can also be changed by selections in the pop-up printer dialogs. When paper size or orientation is changed via the pop-up dialog, the auto_lpp will adjust for those. If you're specifying fonts manually, or auto_lpp is FALSE, you'll have to set these in advance.

Your program can override many other settings exported by GtkPrinter.e, some of the most useful being:

Customized page headers and/or footers (see headers)
paper_name default is us_letter, see resources/papersizes.txt
lines_per_page default is 58
use_line_numbers default is TRUE
use_color default is TRUE; currently, only prints Eu comments in red
font the usual font description: e.g. "Courier 12", or "Georgia bold 16"...
show_progress default is TRUE, see progress bar
orientation portrait, landscape
quality draft, etc.
number_up print 2-up or 4-up on a single sheet
number_up_layout see GTK docs
Margins top_margin, left_margin, etc.; default is .25 inch
units default is GTK_UNIT_INCH
scale default is 100%
n_pages max number of pages to print, defaults to full document
order 0 = normal (first to last page), 1 = reverse (last to first)
name printer name
plaintext set to TRUE to print text containing < or > or & chars
wrap_at default is 0 (no wrap)
tabs replace each tab with spaces or other chars, default is 2 spaces
jobname shown in printer queue, defaults to filename and job #
track_status default is TRUE
settings_file filename to save print job settings to.
-- this is not the same as the GtkSettings ini file!
setup_file see the GTK docs
parent pass the main window handle here [optional]
action one of the following enums: GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG
-- show printer setup dialog, then print (this is the default)
GTK_PRINT_OPERATION_ACTION_PRINT
-- print without showing any dialogs

GTK_PRINT_OPERATION_ACTION_PREVIEW
-- preview only, without dialogs, don't print

GTK_PRINT_OPERATION_ACTION_EXPORT
-- write a pdf to [export_file] without dialogs
export_file name to use for .pdf file
confirm pop up a dialog when job is complete, default is FALSE

Be sure to use the printer: namespace when modifying the above variables. Certain other things, such as selecting a range of pages to print, or putting a job on hold, can only be done by the user in the print setup dialogs at this time.

Printing

Adding print capability to your program is actually pretty easy. There are two main options:

Print from a disk file
Print from in-line or generated text

And, there are two ways to start the print process:

Connect the print_file or print_text function to a button, and attach the filename or text as the button's data item
Call the exported function PrintFile() or PrintText()

Connecting to buttons

Often, you can save a lot of typing by simply connecting a call to print_file or print_text to a button, followed by the file name, file handle or text to print as the data item:

    constant btn1 = create(GtkButton,"gtk-print",print_file,"~/demos/GtkEngine.e")-- default title will be GtkEngine.e
    constant btn2 = create(GtkButton,"gtk-print",print_text,LGPL) 
    constant btn3 = create(GtkButton,"gtk-print",print_file,fn) -- using a Eu file handle to a previously opened file

See test189 and test190 for various ways to call these functions.

Calling via function calls

If you call the print routines via a normal function call, you have the option to add a page title to appear in the header.

    PrintFile("~/demos/GtkEngine.e") -- default title will be "GtkEngine.e"
    PrintFile("License Terms","~/demos/license.txt") -- title will be "License Terms"

See test189 and test190 for various ways to call these functions.

    PrintText("",LGPL) -- no title
    PrintText("Lesser General Public License",LGPL) -- prints "Lesser General Public License" as the title

See test191 to see how to print direct to a .pdf file.

Headers and Footers

You may wish to override the default page header and/or footer formats.
Headers and footers are printed using text:format(), so you can choose what info shows and in what order by using square brackets.
For example:

 printer:header = ""  -- no header
 printer:header = "Title: <b>[1]</b> User: [9]\n\n" -- prints page title (bold) and user name

The numbers in the format box or boxes in the header or footer will be replaced with:

page title heading for all pages, unless there's a subtitle
page subtitle heading to use on pages after pg 1
file name
short name file name w/o path
current page number
n_pages printed
n_copies requested
today's date in date_format
user name
real name
font name used for this print job
file length (bytes) for named files only
file timestamp for named files only
export filename for pdf files

You can use these in any order and combined with other text as you wish. If you define custom headers or footers, be sure to end the header string, and begin the footer string, with one or two '\n' to separate them from the body text!
You may use any of the normal markup tokens in the header and footer, including font and color specifications.

If you use custom headers or footers, be sure to declare them after you call show_all(mainwindow). This way, they won't be accessed until after the GTK engine has been fully initialized. Of course, if you print from a Eu function you have written, you can declare the header and/or footer formats at the start of the function. They won't be set until the function is called.

The current date display format can be changed by overriding printer:date_format.The format is the same as used in std/datetime.e.

Progress Bar

There's a ready-to use progressbar exported by GtkPrinter.e. To use it, just add it in the appropriate place on your window or dialog:

 pack(panel,printer:progress)

The progressbar will be updated automatically. Sometimes it's nice to hide the progressbar until printing begins.

Custom Tabs

You can construct a custom tab and page which will be added to the print dialog. To do so, you will need to override 3 variables in GtkPrinter.e.

custom_tab_label
custom_tab_func
A call_back to your function which creates and returns the handle to a container (GtkBox) with one or more controls embedded.
This will be the contents of your added page.
custom_tab_hook
A call_back to a function which retrieves the settings from your embedded controls and applies them as appropriate.