gtksourceview.SourcePrintJob Print Job object for gtksourceview.SourceView

## Synopsis

gtksourceview.SourcePrintJob gobject.GObject gtksourceview.SourcePrintJob buffer None set_config config get_config set_buffer buffer get_buffer setup_from_view view set_tabs_width tabs_width get_tabs_width set_wrap_mode wrap get_wrap_mode set_highlight highlight get_highlight set_font_desc font_desc get_font_desc set_font highlight get_font set_numbers_font_desc desc get_numbers_font_desc set_numbers_font font_name get_numbers_font get_font set_print_numbers interval get_print_numbers set_text_margins top bottom left right get_text_margins print print_range start end print_range_async start end cancel get_print_job get_page get_page_count get_print_context set_print_header setting get_print_header set_print_footer setting get_print_footer set_header_footer_font_desc desc get_header_footer_font_desc set_header_footer_font font_name get_header_footer_font set_header_format left center right separator set_footer_format left center right separator

## Ancestry

    +-- gobject.GObject
      +-- gtksourceview.SourcePrintJob

## Properties

> "buffer" | Read-Write | The gtksourceview.SourceBuffer to print.
> "config" | Read-Write | Configuration options for the print job.
> "font" | Read-Write | GnomeFont name to use for the document text (deprecated), default None.
> "font-desc" | Read-Write | Font to use for the document text (e.g. "Monospace 10").
> "header-footer-font" | Read-Write | GnomeFont name to use for the header and footer (deprecated), default None.
> "header-footer-font-desc" | Read-Write | Font to use for headers and footers (e.g. "Monospace 10").
> "highlight" | Read-Write | Whether to print the document with highlighted syntax, default True.
> "numbers-font" | Read-Write | GnomeFont name to use for the line numbers (deprecated), default None.
> "numbers-font-desc" | Read-Write | Font description to use for the line numbers (e.g. "Monospace 10").
> "print-footer" | Read-Write | Whether to print a footer in each page, default False.
> "print-header" | Read-Write | Whether to print an header in each page, default False.
> "print-numbers" | Read-Write | Interval of printed line numbers (0 means no numbers), allowed values: minor or equal to 100, default value: 1.
> "tabs-width" | Read-Write | Width in equivalent space characters of tabs, allowed values: minor or equal to 100, default value: 8.
> "wrap-mode" | Read-Write | Word wrapping mode, default value: GTK_WRAP_NONE.

## Signal Prototypes

"begin-page"
  callback sourceprintjob arg1 user_param1 ...
"finished"
  callback sourceprintjob arg1 user_param1 ...

## Description

The gtksourceview.SourcePrintJob object is used to print the contents of a gtksourceview.SourceBuffer. You can set various configuration options to customize the printed output, and the result is obtained as a gtksourceview.SourcePrintJob object, which you can then preview with gnomeprint.ui.JobPreview or print directly with gnomeprint.Job.print

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 gtksourceview.SourcePrintJob is to produce a gnomeprint.Job. What this means is that once you get the resulting gnomeprint.Job, you might reuse the gtksourceview.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 gtksourceview.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 gtksourceview.SourceView, line numbers, basic headers and footers.

gtksourceview.SourcePrintJob can print basic headers and footers in each page. You can specify the time like strings for text on the left, right and center of the top and bottom of the page. You can also make gtksourceview.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 gtksourceview.SourcePrintJob is about to print a new text page, the signal will be emitted. You can then get the gnomeprint.Context 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 gnomeprint.Config, but outside all print area used by gtksourceview.SourcePrintJob itself.

## Constructor

    	  gtksourceview.SourcePrintJob
    	  bufferNone

buffer :

  a gtksourceview.SourceBuffer or `None`

Returns :

  a new gtksourceview.SourcePrintJob.

Creates a new gtksourceview.SourcePrintJob object.

## Methods

### gtksourceview.SourcePrintJob.set_config

    	  set_config
    	  config

config :

  a gnomeprint.Config object to get printing configuration from.

The set_config() method sets the print configuration for the job. If you don't set a configuration object for the print job, when needed one will be created with gnomeprint.Config

### gtksourceview.SourcePrintJob.get_config

    	  get_config

Returns :

  the gnomeprint.Config for the print job.

The get_config() method gets the current gnomeprint.Config the print job will use. If not previously set, this will create a default configuration and return it. The returned object reference is owned by the print job.

### gtksourceview.SourcePrintJob.set_buffer

    	  set_buffer
    	  buffer

buffer :

  a gtksourceview.SourceBuffer.

The set_buffer() method sets the gtksourceview.SourceBuffer the print job will print. You need to specify a buffer to print, either by the use of this function or by creating the print job passing the parameter buffer at the constructor.

### gtksourceview.SourcePrintJob.get_buffer

    	  get_buffer

Returns :

  the gtksourceview.SourceBuffer to print.

The get_buffer() method gets the gtksourceview.SourceBuffer the print job would print. The returned object reference (if non `None`) is owned by the job object and should not be unreferenced

### gtksourceview.SourcePrintJob.setup_from_view

    	  setup_from_view
    	  view

view :

  a gtksourceview.SourceView to get configuration from.

The setup_from_view() method is a convenience function to set several configuration options at once, so that the printed output matches view. The options set are buffer (if not set already), tabs width, highlighting, wrap mode and default font.

### gtksourceview.SourcePrintJob.set_tabs_width

    	  set_tabs_width
    	  tabs_width

tabs_width :

  the number of equivalent spaces for a tabulation.

The set_tabs_width() method sets the width (in equivalent spaces) of tabulations for the printed text. The width in printing units will be calculated as the width of a string containing tabs_width spaces of the default font. Tabulation stops are set for the full width of printed text.

### gtksourceview.SourcePrintJob.get_tabs_width

    	  get_tabs_width

Returns :

  the width (in equivalent spaces) of a tabulation.

The get_tabs_width() method determines the configured width (in equivalent spaces) of tabulations. The default value is 8.

### gtksourceview.SourcePrintJob.set_wrap_mode

    	  set_wrap_mode
    	  wrap

wrap :

  the wrap mode.

The set_wrap_mode() method sets the wrap mode for lines of text larger than the printable width. See GtkWrapMode for a definition of the possible values.

### gtksourceview.SourcePrintJob.get_wrap_mode

    	  get_wrap_mode

Returns :

  the current wrapping mode for the print job.

The get_tabs_width() method determines the wrapping style for text lines wider than the printable width. The default is no wrapping.

### gtksourceview.SourcePrintJob.set_highlight

    	  set_highlight
    	  highlight

highlight :

  if `TRUE` the printed text should be highlighted.

The set_highlight() method sets whether the printed text will be highlighted according to the buffer rules. Both color and font style are applied.

### gtksourceview.SourcePrintJob.get_highlight

    	  get_highlight

Returns :

  `TRUE` if the printed output will be highlighted.

The get_tabs_width() method determines if the job is configured to print the text highlighted with colors and font styles. Note that highlighting will happen only if the buffer to print has highlighting activated.

### gtksourceview.SourcePrintJob.set_font_desc

    	  set_font_desc
    	  desc

desc :

  the PangoFontDescription for the default font.

The set_font_desc() method sets the default font for the printed text.

### gtksourceview.SourcePrintJob.get_font_desc

    	  get_font_desc

Returns :

  the current text font description.

The get_font_desc() method determines the default font to be used for the printed text. The returned string is of the form "Fontfamily Style Size", for example "Monospace Regular 10.0".

### gtksourceview.SourcePrintJob.set_font

    	  set_font
    	  font_name

font_name :

  the name of the default font.

The set_font() method sets the default font for the printed text. font_name should be a full font name GnomePrint can understand (e.g. "Monospace Regular 10.0")

Note that font_name is a GnomeFont name not a Pango font description string. This function is deprecated since GnomeFont is no longer used when implementing printing for GtkSourceView; you should use set_font_desc instead.

### gtksourceview.SourcePrintJob.get_font

    	  get_font

Returns :

  a newly allocated string with the name of the current text font.

The get_font() method determines the default font to be used for the printed text. The returned string is of the form "Fontfamily Style Size", for example "Monospace Regular 10.0".

Note that font_name is a GnomeFont name not a Pango font description string. This function is deprecated since GnomeFont is no longer used when implementing printing for GtkSourceView; you should use get_font_desc instead.

### gtksourceview.SourcePrintJob.set_numbers_font_desc

    	  set_numbers_font_desc
    	  desc

desc :

  the PangoFontDescription for the default font for the line numbers or `None`.

The set_numbers_font_desc() method sets the font for printing line numbers on the left margin. If `None` is supplied, the default font (i.e. the one being used for the text) will be used instead.

### gtksourceview.SourcePrintJob.get_numbers_font_desc

    	  get_numbers_font_desc

Returns :

  the line numbers font description or `None`.

The get_font_desc() method determines the font to be used for the line numbers. This function might return `None` if a specific font for numbers has not been set.

### gtksourceview.SourcePrintJob.set_numbers_font

    	  set_numbers_font
    	  font_name

font_name :

  the full name of the font for line numbers, or `None`.

The set_font() method sets the font for printing line numbers on the left margin. If `None` is supplied, the default font (i.e. the one being used for the text) will be used instead.

Note that font_name is a GnomeFont name not a Pango font description string. This function is deprecated since GnomeFont is no longer used when implementing printing for GtkSourceView; you should use set_numbers_font instead.

### gtksourceview.SourcePrintJob.get_numbers_font

    	  get_numbers_font

Returns :

  a newly allocated string with the name of the current line numbers font, or `None`.

The get_numbers_font() method determines the font to be used for the line numbers. The returned string is of the form "Fontfamily Style Size", for example "Monospace Regular 10.0". This function might return `None` if a specific font for numbers has not been set.

Note that font_name is a GnomeFont name not a Pango font description string. This function is deprecated since GnomeFont is no longer used when implementing printing for GtkSourceView; you should use get_numbers_font instead.

### gtksourceview.SourcePrintJob.set_print_numbers

    	  set_print_numbers
    	  interval

interval :

  interval for printed line numbers.

The set_print_numbers() method sets 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 (i.e. 1 will print all line numbers).

### gtksourceview.SourcePrintJob.get_print_numbers

    	  get_print_numbers

Returns :

  the interval of printed line numbers.

The get_font_desc() method determines the interval used for line number printing. If the value is 0, no line numbers will be printed. The default value is 1 (i.e. numbers printed in all lines).

### gtksourceview.SourcePrintJob.set_text_margins

    	  set_text_margins
    	  top
          bottom
          left
          right

top :

  the top user margin.

bottom :

  the bottom user margin.

left :

  the left user margin.

right :

  the right user margin.

The set_text_margins() method sets the four user margins for the print job. 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.

### gtksourceview.SourcePrintJob.get_text_margins

    	  get_text_margins

Returns :

  a list of margin numbers.

The get_text_margins() method determines the user set margins for the job. 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 `None` if you want to ignore that value.

### gtksourceview.SourcePrintJob.print

    	  print

Returns :

  a closed GnomePrintJob with the printed document, or `None` if printing could not be completed.

The print() method produces a GnomePrintJob with the printed document. The whole contents of the configured gtksourceview.SourceBuffer are printed. The returned job is already closed and ready to be previewed (using gnomeprint.ui.JobPreview) or printed directly. The caller of this function 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.

### gtksourceview.SourcePrintJob.print_range

    	  print_range

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 `None` if job could not print.

The print_range() method is similar to print, except you can specify a range of text to print. The passed GtkTextIter values might be out of order.

### gtksourceview.SourcePrintJob.print_range_async

    	  print_range_async

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.

The print_range_async() method starts to print job asynchronously. This function will ready the job for printing and install an idle handler that will render one page at a time.

This function will not return immediatly, as only page rendering is done asynchronously. Text retrieval and paginating happens within this function. 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

### gtksourceview.SourcePrintJob.cancel

    	  cancel

The cancel() method 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), but it will not be closed either. If you wish to show or print the partially printed document you need to close it yourself.

This function has no effect when called from a non-asynchronous print operation.

### gtksourceview.SourcePrintJob.get_print_job

    	  get_print_job

Returns :

  a new reference to the job's GnomePrintJob, or `None`.

The get_font_desc() method gets a reference to the GnomePrintJob which the job is printing or has recently finished printing. You need to unref the returned object.

You may call this function 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.

### gtksourceview.SourcePrintJob.get_page

    	  get_page

Returns :

  the current page number.

The get_page() method determines the currently printing page number. This function is only valid while printing (either synchronously or asynchronously).

### gtksourceview.SourcePrintJob.get_page_count

    	  get_page_count

Returns :

  the number of pages of the printed job.

The get_page_count() method determines the total number of pages the job will print. 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_range_async has returned.

### gtksourceview.SourcePrintJob.get_print_context

    	  get_print_context

Returns :

  the current GnomePrintContext. The returned object is owned by job.

The get_print_context() method determines the GnomePrintContext of the current job. This function is only valid while printing. Normally you would use this function to print in the margins set by set_text_margins in a handler for the "begin-page" signal.

### gtksourceview.SourcePrintJob.set_print_header

    			  set_print_header
    			  setting

setting :

  if `TRUE` you want the header to be printed.

The set_print_header() method sets whether you want to print a header in each page. The default header consists of three pieces of text and an optional line separator, configurable with set_header_format.

### gtksourceview.SourcePrintJob.get_print_header

    			  get_print_header

Returns :

  `TRUE` if the header is set to be printed.

The get_print_header() method Determines if a header is set to be printed for each page. A header will be printed if this function returns `TRUE` and some format strings have been specified with set_header_format.

### gtksourceview.SourcePrintJob.set_print_footer

                  set_print_footer
                  setting

setting :

  if `TRUE` you want the footer to be printed.

The set_print_footer() method sets whether you want to print a footer in each page. The default header consists of three pieces of text and an optional line separator, configurable with set_footer_format.

By default the footer format is unspecified, and if it's empty it will not be printed, regardless of this setting.

### gtksourceview.SourcePrintJob.get_print_footer

                  get_print_footer

Returns :

  `TRUE` if the footer is set to be printed.

The get_print_footer() method determines if a footer is set to be printed for each page. A header will be printed if this function returns `TRUE` and some format strings have been specified with set_header_format.

### gtksourceview.SourcePrintJob.set_header_footer_font_desc

                  set_header_footer_font_desc
                  desc

desc :

  the PangoFontDescription for the font to be used in headers and footers, or `None`.

The set_header_footer_font_desc() method sets the font for printing headers and footers. If `None` is supplied, the default font (i.e. the one being used for the text) will be used instead.

### gtksourceview.SourcePrintJob.get_header_footer_font_desc

                  get_header_footer_font_desc

Returns :

  the header and footer font description or `None`.

The get_header_footer_font_desc() method determines the font to be used for the header and footer. This function might return `None` if a specific font has not been set.

### gtksourceview.SourcePrintJob.set_header_footer_font

                  set_header_footer_font
                  font_name

font_name :

  the full name of the font to be used in headers and footers, or `None`.

The set_header_footer_font() method sets the font for printing headers and footers. If `None` is supplied, the default font (i.e. the one being used for the text) will be used instead.

the result is a GnomeFont name not a Pango font description string. This function is deprecated since GnomeFont is no longer used when implementing printing for gtksourceview.SourceView; you should use set_header_footer_font_desc instead.

### gtksourceview.SourcePrintJob.get_header_footer_font

                  get_header_footer_font

Returns :

  a newly allocated string with the name of the current header and footer font, or `None`.

The get_header_footer_font_desc() method determines the font to be used for the header and footer. The returned string is of the form "Fontfamily Style Size", for example "Monospace Regular 10.0". The returned value should be freed when no longer needed. This function might return `None` if a specific font has not been set.

the result is a GnomeFont name not a Pango font description string. This function is deprecated since GnomeFont is no longer used when implementing printing for gtksourceview.SourceView; you should use get_header_footer_font_desc instead.

### gtksourceview.SourcePrintJob.set_header_format

                  set_header_format
                  left
                  center
                  right
                  separator

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.

right :

  `TRUE` if you want a separator line to be printed.

The set_header_format() method sets time() like header format strings, to be printed on the left, center and right of the top of each page. The strings may include strftime(3) codes which will be expanded at print time. All time() codes are accepted, with the addition of N for the page number and Q for the page count.

Separator specifies if a solid line should be drawn to separate the header from the document text.

If `None` 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.

### gtksourceview.SourcePrintJob.set_footer_format

                  set_footer_format
                  left
                  center
                  right
                  separator

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.

right :

  `TRUE` if you want a separator line to be printed.

The set_footer_format() method sets time() like footer format strings, to be printed on the left, center and right of the top of each page. The strings may include strftime(3) codes which will be expanded at print time. All time() codes are accepted, with the addition of N for the page number and Q for the page count.

Separator specifies if a solid line should be drawn to separate the header from the document text.

If `None` 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_footer.

## Signals

### The "begin-page" gtksourceprintjob.SourcePrintJob Signal

    	  callback
    	  sourceprintjob
          user_param1
    	  ...

sourceprintjob :

  the sourceprintjob that received the signal

user_param1 :

  the first user parameter (if any) specified with the connect() method

... :

  additional user parameters (if any)

The "begin-page" signal is emitted when the sourceprintjob 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.

### The "finished" gtksourceprintjob.SourcePrintJob Signal

    	  callback
    	  sourceprintjob
          user_param1
    	  ...

sourcebuffer :

  the sourcebuffer that received the signal

user_param1 :

  the first user parameter (if any) specified with the connect() method

... :

  additional user parameters (if any)

The "finished" signal is emitted 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 sourceprintjob was producing has been closed and it can be either previewed or printed to the physical device.