Reference Manual
Inti Logo
Main Page | Namespace List | Class Hierarchy | Alphabetical List | Compound List | File List | Namespace Members | Compound Members | File Members

Inti::Gtk::SourcePrintJob Class Reference

A GtkSourcePrintJob C++ wrapper class. More...

#include <inti/gtk-sourceview/sourceprintjob.h>

List of all members.

Public Member Functions

Constructors
Accessors
Methods
Property Proxies
Signal Proxies

Protected Member Functions

Constructors
Signal Handlers

Detailed Description

A GtkSourcePrintJob C++ wrapper class.

The SourcePrintJob object is used to print the contents of a SourceBuffer. You can set various configuration options to customize the printed output, and the result is obtained as a GnomePrintJob object, which you can then preview with gnome_print_job_preview_new() or print directly with gnome_print_job_print().

The easiest way to construct a new print job is from a SourceView. In this case the print job's buffer, tabs width, highlight, wrap mode, and font will be set to the values currently set in the source view. Other constructors take a SourceBuffer, a GnomePrintConfig object or both. If a GnomePrintConfig is not specified the print job will use the default gnome print configuration. If no font is set the print job will use the default font: 'Monospace Regular 10'.

Printing can be done synchronously and asynchronously. Asynchronous methods are provided so you can give the user feedback about what's going on when printing long documents (see the "begin_page" and "finished" signals).

The task of a SourcePrintJob is to produce a GnomePrintJob. What this means is that once you get the resulting GnomePrintJob, you might reuse the SourcePrintJob to produce another output (with different configuration options for example) or just unreference it and forget about it. The lifetime of the produced object is independent of that of the producer.

Before printing you should at least set the SourceBuffer you want to print (using set_buffer()). Besides that, you might configure word wrapping, font, whether to print hightlighted text as seen in the SourceView, line numbers, basic headers and footers.

SourcePrintJob can print basic headers and footers in each page. You can specify strftime() like strings for text on the left, right and center of the top and bottom of the page. You can also make SourcePrintJob draw a separator line between the text document and the header and footer. And you can specify a different font (from that used for the text document).

Customization beyond that is possible, but you have to do the printing manually. To do that, you need to connect to the "begin_page" signal of the job and allocate some space in the page using set_text_margins(). Whenever SourcePrintJob is about to print a new text page, the signal will be emitted. You can then get the GnomePrintContext being used with get_print_context() and use Gnome Print functions directly. The space you allocate is inside the document margins defined in the specified GnomePrintConfig, but outside all print area used by SourcePrintJob itself.

Example: A quick bootstrap code sequence to get you started using SourcePrintJob: 

    GnomePrintJob *
    print_source_buffer_from_view(Gtk::SourceView& view, const String& title)
    {
        // Create a job using the default print configuration and setup the buffer,
        // font and wrapping with those values set in the source view.
        Pointer<Gtk::SourcePrintJob> job = new Gtk::SourcePrintJob(*view);
   
        // Print line numbers every 5 lines, using the default font.
        job->set_print_numbers(5);
   
        // Print a header with the title centered.
        job->set_header_footer_font("Sans Regular 12.0");
        job->set_header_format(0, title, 0, true);
        job->set_print_header(true);
   
        // Print the page number in the page bottom.
        job->set_footer_format(0, 0, "Page N of Q", true);
        job->set_print_footer(true);
   
        // Print the whole buffer and return the result (that is, a GnomePrintJob pointer).
        return job->print();
    }

Constructor & Destructor Documentation

Inti::Gtk::SourcePrintJob::SourcePrintJob (  GtkSourcePrintJob *  job,
bool  reference = false
)  [explicit, protected]
 

Construct a new SourcePrintJob from an existing GtkSourcePrintJob.

Parameters:
job A pointer to a GtkSourcePrintJob.
reference Set false if the initial reference count is floating, set true if it's not.

The job can be a newly created GtkSourcePrintJob or an existing GtkSourcePrintJob (see G::Object::Object).

Inti::Gtk::SourcePrintJob::SourcePrintJob (  SourceBuffer *  buffer = 0  )  [explicit]
 

Constructs a new source print job.

Parameters:
buffer The SourceBuffer to print, or null.

If no GnomePrintConfig is set by calling set_config() the print job will use the default gnome print configuration.

Inti::Gtk::SourcePrintJob::SourcePrintJob (  GnomePrintConfig &  config,
SourceBuffer *  buffer = 0
)  [explicit]
 

Constructs a new source print job with the specified configuration.

Parameters:
config The print job options.
buffer The SourceBuffer to print, or null.

Inti::Gtk::SourcePrintJob::SourcePrintJob (  SourceView &  view  )  [explicit]
 

Convenience constructor that sets several configuration options at once, so that the printed output matches the view.

Parameters:
view The SourceView to get the configuration from.

The configuration options set are the buffer, tabs width, highlighting, wrap mode and default font. This is the easiest way to set up a print job. If no configuration is set later the default GnomePrintConfig is used.

Member Function Documentation

void Inti::Gtk::SourcePrintJob::cancel (   ) 
 

Cancels an asynchronous printing operation.


This will remove any pending print idle handler and unref the current GnomePrintJob. Note that if you got a reference to the job's GnomePrintJob (using get_print_job()) it will not be destroyed (since you hold a reference to it), and it will not be closed either. If you wish to show or print the partially printed document you need to close it yourself. This method has no effect when called from a non-asynchronous print operation.

SourceBuffer* Inti::Gtk::SourcePrintJob::get_buffer (   )  const
 

Gets the SourceBuffer the print job would print.

Returns:
The SourceBuffer to print.

GnomePrintConfig* Inti::Gtk::SourcePrintJob::get_config (   )  const
 

Gets the current GnomePrintConfig the print job will use.

Returns:
A pointer to the GnomePrintConfig for the print job.

If not previously set, this will create a default configuration and return it.

String Inti::Gtk::SourcePrintJob::get_font (   )  const
 

Gets the default font to be used for the printed text.

Returns:
A String with the name of the current text font.

The returned string is of the form "Fontfamily Style Size", for example "Monospace Regular 10.0".

String Inti::Gtk::SourcePrintJob::get_header_footer_font (   )  const
 

Gets the font to be used for the header and footer.

Returns:
A String with the name of the current header and footer font, or null.

The returned string is of the form "Fontfamily Style Size", for example "Monospace Regular 10.0". This method might return null if a specific font has not been set.

bool Inti::Gtk::SourcePrintJob::get_highlight (   )  const
 

Gets whether the job is configured to print the text highlighted with colors and font styles.

Returns:
true if the printed output will be highlighted.

Note that highlighting will happen only if the buffer to print has highlighting activated.

String Inti::Gtk::SourcePrintJob::get_numbers_font (   )  const
 

Gets the font to be used for the line numbers.

Returns:
A String with the name of the current line numbers font, or null.

The returned string is of the form "Fontfamily Style Size", for example "Monospace Regular 10.0". This function might return a null String if a specific font for line numbers has not been set.

unsigned int Inti::Gtk::SourcePrintJob::get_page (   )  const
 

Gets the currently printing page number.

Returns:
The current page number.

This method is only valid while printing (either synchronously or asynchronously).

unsigned int Inti::Gtk::SourcePrintJob::get_page_count (   )  const
 

Obtains the total number of pages the job will print.

Returns:
The number of pages of the printed job.

The returned value is only meaninful after pagination has finished. In practice, for synchronous printing this means when "begin_page" is emitted, or after print_async() has returned.

GnomePrintContext* Inti::Gtk::SourcePrintJob::get_print_context (   )  const
 

Gets the GnomePrintContext of the current job.

Returns:
The current GnomePrintContext

This method is only valid while printing. Normally you would use this method to print in the margins set by set_margins() in a handler for the "begin_page" signal. The returned object is owned by job.

bool Inti::Gtk::SourcePrintJob::get_print_footer (   )  const
 

Determines if a footer is set to be printed for each page.

Returns:
true if the footer is set to be printed.

A footer will be printed if this method returns true and some format strings have been specified with set_footer_format().

bool Inti::Gtk::SourcePrintJob::get_print_header (   )  const
 

Determines if a header is set to be printed for each page.

Returns:
true if the header is set to be printed.

A header will be printed if this method returns true and some format strings have been specified with set_header_format().

GnomePrintJob* Inti::Gtk::SourcePrintJob::get_print_job (   )  const
 

Gets a reference to the GnomePrintJob which the job is printing or has recently finished printing.

Returns:
A new reference to the job's GnomePrintJob, or null.

Note you need to unref the returned object. You may call this method in the middle of an asynchronous printing operation, but the returned GnomePrintJob will not be closed until the last page is printed and the "finished" signal is emitted.

unsigned int Inti::Gtk::SourcePrintJob::get_print_numbers (   )  const
 

Obtains the interval used for line number printing.

Returns:
The interval of printed line numbers.

If the return value is 0, no line numbers will be printed. The default value is 1 (that is, line numbers are printed on all lines).

unsigned int Inti::Gtk::SourcePrintJob::get_tabs_width (   )  const
 

Gets the configured tabs width in equivalent spaces (the default value is 8).

Returns:
The tabs width in equivalent spaces.

void Inti::Gtk::SourcePrintJob::get_text_margins (  double *  top,
double *  bottom,
double *  left,
double *  right
)  const
 

Gets the user set margins for the print job.

Parameters:
top The location to store the top margin.
bottom The location to store the bottom margin.
left The location to store the left margin.
right The location to store the right margin.

This function retrieves the values previously set by set_text_margins(). The default for all four margins is 0. Any of the pointers can be null if you want to ignore that value.

WrapMode Inti::Gtk::SourcePrintJob::get_wrap_mode (   )  const
 

Gets the wrapping style for text lines wider than the printable width.

Returns:
The current wrapping mode for the print job.

The default is no wrapping.

virtual void Inti::Gtk::SourcePrintJob::on_begin_page (   )  [protected, virtual]
 

Called whenever the print job is about to print a new text page.

You can connect to this signal to provide the user with feedback about the progress of printing, or to customize the printed page by for example, printing your own headers and footers.

virtual void Inti::Gtk::SourcePrintJob::on_finished (   )  [protected, virtual]
 

Called whenever an asynchronous print job has finished.

You can connect to this signal to get notification when a job has finished printing. When it's emitted, the GnomePrintJob the print job was producing has been closed and it can be either previewed or printed to the physical device.

GnomePrintJob* Inti::Gtk::SourcePrintJob::print (  const TextIter &  start,
const TextIter &  end
) 
 

Produces a GnomePrintJob with the source buffer range from start to end.

Parameters:
start The start of the region of text to print.
end The end of the region of text to print.
Returns:
A closed GnomePrintJob with the text from start to end printed, or null if job could not print.

The returned GnomePrintJob pointer is referenced and so must be unreferenced when no longer required.

GnomePrintJob* Inti::Gtk::SourcePrintJob::print (   ) 
 

Produces a GnomePrintJob with the printed document.

Returns:
A closed GnomePrintJob with the printed document, or null if printing could not be completed.

The whole contents of the configured SourceBuffer are printed. The returned job is already closed and ready to be previewed (using gnome_print_job_preview_new()) or printed directly. The caller of this method owns a reference to the returned object, so job can be destroyed and the output will still be valid, or the document can be printed again with different settings.

bool Inti::Gtk::SourcePrintJob::print_async (  const TextIter &  start,
const TextIter &  end
) 
 

Starts to print the job asynchronously.

Parameters:
start The start of the region of text to print.
end The end of the region of text to print.
Returns:
true if the print started.

This method will ready the job for printing and install an idle handler that will render one page at a time. This method will not return immediatly, as only page rendering is done asynchronously. Text retrieval and paginating happens within this method. Also, if highlighting is enabled, the whole buffer needs to be highlighted first. To get notification when the job has finished, you must connect to the "finished" signal. After this signal is emitted you can retrieve the resulting GnomePrintJob with get_print_job(). You may cancel the job with cancel().

void Inti::Gtk::SourcePrintJob::set_buffer (  SourceBuffer &  buffer  ) 
 

Sets the SourceBuffer the print job will print.

Parameters:
buffer The SourceBuffer to print.

You need to specify a buffer to print, either by using this method or by specifying a buffer when you construct the print job.

void Inti::Gtk::SourcePrintJob::set_config (  GnomePrintConfig &  config  ) 
 

Sets the print configuration for the job.

Parameters:
config A GnomePrintConfig object to get printing configuration from.

If you don't set a configuration object for the print job, when needed one will be created with gnome_print_config_default().

void Inti::Gtk::SourcePrintJob::set_font (  const String &  font_name  ) 
 

Sets the default font for the printed text.

Parameters:
font_name The name of the font used for the document text.

The font_name should be a full font name GnomePrint can understand. The default font name is "Monospace Regular 10";

void Inti::Gtk::SourcePrintJob::set_footer_format (  const String &  left,
const String &  center,
const String &  right,
bool  separator
) 
 

Sets strftime-like footer format strings, to be printed on the left, center and right of the bottom of each page (see set_header_format()).

Parameters:
left A format string to print on the left of the footer.
center A format string to print on the center of the footer.
right A format string to print on the right of the footer.
separator Set true if you want a separator line to be printed.

void Inti::Gtk::SourcePrintJob::set_header_footer_font (  const String &  font_name  ) 
 

Sets the font for printing headers and footers.

Parameters:
font_name The full name of the font to be used in headers and footers, or null.

If a null String is supplied, the default font (that is, the one being used for the text) will be used instead. The default font name is 'Monospace Regular 10';

void Inti::Gtk::SourcePrintJob::set_header_format (  const String &  left,
const String &  center,
const String &  right,
bool  separator
) 
 

Sets strftime-like header format strings, to be printed on the left, center and right of the top of each page.

Parameters:
left A format string to print on the left of the header.
center A format string to print on the center of the header.
right A format string to print on the right of the header.
separator Set true if you want a separator line to be printed.

The strings may include strftime(3) codes which will be expanded at print time. All strftime() codes are accepted (A for the day, F for the date, T for the time), with the addition of N for the page number and Q for the total page count. separator specifies if a solid line should be drawn to separate the header from the document text. If a null String is given for any of the three arguments, that particular string will not be printed. For the header to be printed, in addition to specifying format strings, you need to enable header printing with set_print_header().

void Inti::Gtk::SourcePrintJob::set_highlight (  bool  highlight  ) 
 

Sets whether the printed text will be highlighted according to the buffer rules.

Parameters:
highlight Set true if the printed text should be highlighted.

If highlight is true both color and font style are applied.

void Inti::Gtk::SourcePrintJob::set_numbers_font (  const String &  font_name  ) 
 

Sets the font for printing line numbers on the left margin.

Parameters:
font_name The full name of the font for line numbers, or null.

If a null String is supplied, the default font (that is, the one being used for the text) will be used instead.

void Inti::Gtk::SourcePrintJob::set_print_footer (  bool  setting  ) 
 

Sets whether you want to print a footer in each page.

Parameters:
setting Set true if you want the footer to be printed.

The default footer consists of three pieces of text and an optional line separator, configurable with set_footer_format(). Note that by default the footer format is unspecified, and if it's empty it will not be printed, regardless of this setting.

void Inti::Gtk::SourcePrintJob::set_print_header (  bool  setting  ) 
 

Sets whether you want to print a header in each page.

Parameters:
setting Set true if you want the header to be printed.

The default header consists of three pieces of text and an optional line separator, configurable with set_header_format(). Note that by default the header format is unspecified, and if it's empty it will not be printed, regardless of this setting.

void Inti::Gtk::SourcePrintJob::set_print_numbers (  unsigned int  interval  ) 
 

Sets the interval for printed line numbers.

Parameters:
interval The interval for printed line numbers.

If interval is 0 no numbers will be printed. If greater than 0, a number will be printed every interval lines (that is, 1 will print a number on every line, 2 will print a number on every second line, 3 will print a number on every third line, and so on).

void Inti::Gtk::SourcePrintJob::set_tabs_width (  unsigned int  tabs_width  ) 
 

Sets the tabs width (in equivalent spaces) for the printed text.

Parameters:
tabs_width The number of equivalent spaces for the tabs width.

The width in printing units will be calculated as the width of a string containing tabs_width spaces of the default font. Tab stops are set for the full width of printed text.

void Inti::Gtk::SourcePrintJob::set_text_margins (  double  top,
double  bottom,
double  left,
double  right
) 
 

Sets the four user margins for the print job.

Parameters:
top The top user margin.
bottom The bottom user margin.
left The left user margin.
right The right user margin.

These margins are in addition to the document margins provided in the GnomePrintConfig and will not be used for headers, footers or line numbers (those are calculated separatedly). You can print in the space allocated by these margins by connecting to the "begin_page" signal. The space is around the printed text, and inside the margins specified in the GnomePrintConfig.

The margin numbers are given in device units. If any of the given values is less than 0, that particular margin is not altered by this function.

void Inti::Gtk::SourcePrintJob::set_wrap_mode (  WrapMode  wrap  ) 
 

Sets the wrap mode for lines of text larger than the printable width.

Parameters:
wrap A WrapMode.

The documentation for this class was generated from the following file: Main Page - Footer

Generated on Wed Aug 27 21:17:28 2003 for Inti-SourceView by doxygen 1.3.2 written by Dimitri van Heesch, © 1997-2002