gtksourceview2.PrintCompositor
Prev |  | Next

## gtksourceview2.PrintCompositor

gtksourceview2.PrintCompositor — Compose a GtkSourceBuffer for printing.

## Synopsis

    class gtksourceview2.PrintCompositor(gobject.GObject):
        gtksourceview2.PrintCompositor(buffer)
        def draw_page(context, page_nr)
        def get_body_font_name()
        def get_bottom_margin(unit)
        def get_buffer()
        def get_footer_font_name()
        def get_header_font_name()
        def get_highlight_syntax()
        def get_left_margin(unit)
        def get_line_numbers_font_name()
        def get_n_pages()
        def get_pagination_progress()
        def get_print_footer()
        def get_print_header()
        def get_print_line_numbers()
        def get_right_margin(unit)
        def get_tab_width()
        def get_top_margin(unit)
        def get_wrap_mode()
        def paginate(context)
        def set_body_font_name(font_name)
        def set_bottom_margin(margin, unit)
        def set_footer_font_name(font_name)
        def set_footer_format(separator, left, center, right)
        def set_header_font_name(font_name)
        def set_header_format(separator, left, center, right)
        def set_highlight_syntax(highlight)
        def set_left_margin(margin, unit)
        def set_line_numbers_font_name(font_name)
        def set_print_footer(print)
        def set_print_header(print)
        def set_print_line_numbers(interval)
        def set_right_margin(margin, unit)
        def set_tab_width(width)
        def set_top_margin(margin, unit)
        def set_wrap_mode(wrap_mode)

    Functions

        def gtksourceview2.print_compositor_new_from_view(view)

## Ancestry

    +-- gobject.GObject
        +-- gtksourceview2.PrintCompositor

## Properties

"body-font-name" | Read-Write | Name of the font used for the text body. Accepted values are strings representing a font description Pango can understand. (e.g. "Monospace 10"). See `pango.FontDescription`() constructor for a description of the format of the string representation. The value of this property cannot be changed anymore after the firstcall to the `gtksourceview2.PrintCompositor.paginate`() method. Default value: `None`. Since 2.2.
"buffer" | Read-Write-Construct | The `gtksourceview2.Buffer` object to print. Since 2.2.
"footer-font-name" | Read-Write | Name of the font used to print page footer. If this property is unspecified, the text body font is used. Accepted values are strings representing a font description Pango can understand. (e.g. "Monospace 10"). See `pango.FontDescription`() constructor for a description of the format of the string representation. The value of this property cannot be changed anymore after the first callto the `gtksourceview2.PrintCompositor.paginate`() method. Default value: `None`. Since 2.2.
"header-font-name" | Read-Write | Name of the font used to print page footer. If this property is unspecified, the text body font is used. Accepted values are strings representing a font description Pango can understand. (e.g. "Monospace 10"). See `pango.FontDescription`() constructor for a description of the format of the string representation. The value of this property cannot be changed anymore after the first callto the `gtksourceview2.PrintCompositor.paginate`() method. Default value: `None`. Since 2.2.
"highlight-syntax" | Read-Write | Whether to print the document with highlighted syntax. The value of this property cannot be changed anymore after the first call to the `gtksourceview2.PrintCompositor.paginate`() method. Default value: `True`. Since 2.2.
"line-numbers-font-name" | Read-Write | Name of the font used to print page footer. If this property is unspecified, the text body font is used. Accepted values are strings representing a font description Pango can understand. (e.g. "Monospace 10"). See `pango.FontDescription`() constructor for a description of the format of the string representation. The value of this property cannot be changed anymore after the first callto the `gtksourceview2.PrintCompositor.paginate`() method. Default value: `None`. Since 2.2.
"n-pages" | Read | The number of pages in the document or -1 if the document has not been completely paginated. Allowed values: >= -1. Default value: -1. Since 2.2
"print-footer" | Read-Write | Whether to print a footer in each page. Note that by default the footer format is unspecified, and if it is unspecified the footer will not be printed, regardless of the value of this property. The value of this property cannot be changed anymore after the first call to the `gtksourceview2.PrintCompositor.paginate`() method. Default value: `False`. Since 2.2.
"print-header" | Read-Write | Whether to print a header in each page. Note that by default the header format is unspecified, and if it is unspecified the header will not be printed, regardless of the value of this property. The value of this property cannot be changed anymore after the first call to the `gtksourceview2.PrintCompositor.paginate`() method. Default value: `False`. Since 2.2.
"print-line-numbers" | Read-Write | Interval of printed line numbers. If this property is set to 0 no numbers will be printed. If greater than 0, a number will be printed every "print-line-numbers" lines (i.e. 1 will print all line numbers). The value of this property cannot be changed anymore after the first call to the `gtksourceview2.PrintCompositor.paginate`() method. Allowed values: <= 100. Default value: 1. Since 2.2.
"tab-width" | Read-Write | Width of a tab character expressed in spaces. The value of this property cannot be changed anymore after the first call to the `gtksourceview2.PrintCompositor.paginate`() method. Allowed values: [1,32]. Default value: 8. Since 2.2.
"wrap-mode" | Read-Write | Whether to wrap lines never, at word boundaries, or at character boundaries. The value of this property cannot be changed anymore after the first call to the `gtksourceview2.PrintCompositor.paginate`() method. Default value: gtk.WRAP_NONE. Since 2.2.

## Description

The `gtksourceview2.PrintCompositor` object is used to compose a `gtksourceview2.buffer` for printing. You can set various configuration options to customize the printed output. `gtksourceview2.PrintCompositor` is designed to be used with the high-level printing API of gtk+, i.e. `gtk.PrintOperation`.

The margins specified in this object are the layout margins: they define the blank space bordering the printed area of the pages. They must not be confused with the "print margins", i.e. the parts of the page that the printer cannot print on, defined in the `gtk.PageSetup` objects. If the specified layout margins are smaller than the "print margins", the latter ones are used as a fallback by the `gtksourceview2.PrintCompositor` object, so that the printed area is not clipped.

## Constructor

        gtksourceview2.PrintCompositor(buffer)

`buffer` : | a `gtksourceview2.Buffer`
Returns : | a new `gtksourceview2.PrintCompositor`.

Creates a new `gtksourceview2.PrintCompositor` that can be used to print buffer.

## Methods

### gtksourceview2.PrintCompositor.draw_page

        def draw_page(context, page_nr)

`context` : | the `gtk.PrintContext` encapsulating the context information that is required when drawing the page for printing.
`page_nr` : | the number of the page to print.

The `draw_page`() method draws page `page_nr` for printing on the the Cairo context encapsuled in context. This method has been designed to be called in the handler of the "draw_page" signal as shown in the following example:

    # Signal handler for the GtkPrintOperation::draw_page signal

    def draw_page(operation, context, page_nr, compositor)
        compositor.draw_page(context, page_nr)

### gtksourceview2.PrintCompositor.get_body_font_name

        def get_body_font_name()

Returns : | a new string containing the name of the font used to print the text body.

The `get_body_font_name`() method returns the name of the font used to print the text body.

### gtksourceview2.PrintCompositor.get_bottom_margin

        def get_bottom_margin(unit)

`unit` : | the unit for the return value.
Returns : | the bottom margin.

The `get_bottom_margin`() method gets the bottom margin in units of `unit`.

### gtksourceview2.PrintCompositor.get_buffer

        def get_buffer()

Returns : | the `gtksourceview2.Buffer` associated with the compositor.

The `get_buffer`() method gets the `gtksourceview2.Buffer` associated with the compositor.

### gtksourceview2.PrintCompositor.get_footer_font_name

        def (get_footer_font_name)

Returns : | a new string containing the name of the font used to print the page footer.

The `get_footer_font_name`() method returns the name of the font used to print the page footer.

### gtksourceview2.PrintCompositor.get_header_font_name

        def get_header_font_name()

Returns : | a new string containing the name of the font used to print the page header.

The `get_header_font_name`() method Returns the name of the font used to print the page header

### gtksourceview2.PrintCompositor.get_highlight_syntax

        def get_highlight_syntax()

Returns : | `True` if the printed output will be highlighted.

The `get_highlight_syntax`() method determines whether the printed text will be highlighted according to the buffer rules. Note that highlighting will happen only if the buffer to print has highlighting activated.

### gtksourceview2.PrintCompositor.get_left_margin

        def get_left_margin(unit)

`unit` : | the unit for the return value.
Returns : | the left margin

The `get_left_margin`() method gets the left margin in units of `unit`.

### gtksourceview2.PrintCompositor.get_line_numbers_font_name

        def get_line_numbers_font_name()

Returns : | a new string containing the name of the font used to print line numbers on the left margin.

The `get_line_numbers_font_name`() method returns the name of the font used to print line numbers on the left margin.

### gtksourceview2.PrintCompositor.get_n_pages

        def get_n_pages()

Returns : | the number of pages in the document or -1 if the document has not been completely paginated.

The `get_n_pages`() method returns the number of pages in the document or -1 if the document has not been completely paginated.

### gtksourceview2.PrintCompositor.get_pagination_progress

        def get_pagination_progress()

Returns : | a fraction from 0.0 to 1.0 inclusive

The `get_pagination_progress`() method returns the current fraction of the document pagination that has been completed.

### gtksourceview2.PrintCompositor.get_print_footer

        def 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 footer will be printed if this function returns `True` and some format strings have been specified with `gtksourceview2.PrintCompositor.set_footer_format`().

### gtksourceview2.PrintCompositor.get_print_header

        def 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 `gtksourceview2.PrintCompositor.set_header_format`().

### gtksourceview2.PrintCompositor.get_print_line_numbers

        def get_print_line_numbers()

Returns : | the interval of printed line numbers.

The `get_print_line_numbers`() method returns 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).

### gtksourceview2.PrintCompositor.get_right_margin

        def get_right_margin(unit)

`unit` : | the unit for the return value.
Returns : | the right margin

The `get_right_margin`() method gets the right margin in units of `unit`.

### gtksourceview2.PrintCompositor.get_tab_width

        def get_tab_width()

Returns : | width of tab.

The `get_tab_width`() method returns the width of tabulation in characters for printed text.

### gtksourceview2.PrintCompositor.get_top_margin

        def get_top_margin(unit)

`unit` : | the unit for the return value.
Returns : | the top margin

The `get_top_margin`() method gets the top margin in units of `unit`.

### gtksourceview2.PrintCompositor.get_wrap_mode

        def get_wrap_mode()

Returns : | the line wrap mode.

The `get_wrap_mode`() method gets the line wrapping mode for the printed text.

### gtksourceview2.PrintCompositor.paginate

        def paginate(context)

`context` : | the `gtk.PrintContext` encapsulating the context information that is required when drawing the page for printing.
Returns : | `True` if the document has been completely paginated, `False` otherwise.

The `paginate`() method paginate the document associated with the compositor.

In order to support non-blocking pagination, document is paginated in small chunks. Each time `gtksourceview2.PrintCompositor.paginate`() is invoked, a chunk of the document is paginated. To paginate the entire document, `gtksourceview2.PrintCompositor.paginate`() must be invoked multiple times. It returns `True` if the document has been completely paginated, otherwise it returns `False`.

This method has been designed to be invoked in the handler of the "paginate" signal, as shown in the following example:

    # Signal handler for the GtkPrintOperation::paginate signal

    def paginate(operation, context, compositor)
        if compositor.paginate(context):
            n_pages = compositor.get_n_pages()
            operation.set_n_pages(n_pages)
            return True
        else:
            return False

If you don't need to do pagination in chunks, you can simply do it all in the "begin-print" handler, and set the number of pages from there, like in the following example:

    # Signal handler for the GtkPrintOperation::begin-print signal

    def begin_print(operation, context, compositor)
        while compositor.paginate(context):
            n_pages = compositor.get_n_pages()
            operation.set_n_pages(n_pages)

### gtksourceview2.PrintCompositor.set_body_font_name

        def set_body_font_name(font_name)

`font_name` : | the name of the default font for the body of text.

The `set_body_font_name`() method sets the default font for the printed text. `font_name` should be a string representation of a font description Pango can understand. (e.g. "Monospace 10"). See `pango.FontDescription`() for a description of the format of the string representation. This function cannot be called anymore after the first call to the `gtksourceview2.PrintCompositor.paginate`() method.

### gtksourceview2.PrintCompositor.set_bottom_margin

        def set_bottom_margin(margin, unit)

`margin` : | the new bottom margin in units of `unit`
`unit` : | the units for margin

The `set_bottom_margin`() method sets the bottom margin used by compositor.

### gtksourceview2.PrintCompositor.set_footer_font_name

        def set_footer_font_name(font_name)

`font_name` : | the name of the default font for the footer text. or `None`.

The `set_footer_font_name`() method Sets the font for printing the page footer. If `None` is supplied, the default font (i.e. the one being used for the text) will be used instead. `font_name` should be a string representation of a font description Pango can understand. (e.g. "Monospace 10"). See `pango.FontDescription`() for a description of the format of the string representation. This function cannot be called anymore after the first call to the `gtksourceview2.PrintCompositor.paginate`() method.

### gtksourceview2.PrintCompositor.set_footer_format

        def set_footer_format(separator, left, center, right)

`separator` : | `True` if you want a separator line to be printed.
`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.

The `set_footer_format`() method sets strftime like header format strings, to be printed on the left, center and right of the bottom of each page. The strings may include strftime(3) codes which will be expanded at print time. All strftime() 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 footer from the document text.

If `None` is given for any of the three arguments, that particular string will not be printed.

For the footer to be printed, in addition to specifying format strings, you need to enable footer printing with `gtksourceview2.PrintCompositor.set_print_footer`().

This method cannot be called anymore after the first call to the `gtksourceview2.PrintCompositor.paginate`() method.

### gtksourceview2.PrintCompositor.set_header_font_name

        def set_header_font_name(font_name)

`font_name` : | the name of the default font for the footer text. or `None`.

The `set_header_font_name`() method Sets the font for printing the page header. If `None` is supplied, the default font (i.e. the one being used for the text) will be used instead. `font_name` should be a string representation of a font description Pango can understand. (e.g. "Monospace 10"). See `pango.FontDescription`() for a description of the format of the string representation. This function cannot be called anymore after the first call to the `gtksourceview2.PrintCompositor.paginate`() method.

### gtksourceview2.PrintCompositor.set_header_format

        def set_header_format(separator, left, center, right)

`separator` : | `True` if you want a separator line to be printed.
`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.

The `set_header_format`() method sets strftime 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 strftime() 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 footer 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 `gtksourceview2.PrintCompositor.set_print_header`().

This method cannot be called anymore after the first call to the `gtksourceview2.PrintCompositor.paginate`() method.

### gtksourceview2.PrintCompositor.set_highlight_syntax

        def set_highlight_syntax(highlight)

`highlight` : | whether syntax should be highlighted.

The `set_highlight_syntax`() method sets whether the printed text will be highlighted according to the buffer rules. Both color and font style are applied. This function cannot be called anymore after the first call to the `gtksourceview2.PrintCompositor.paginate`() method.

### gtksourceview2.PrintCompositor.set_left_margin

        def set_left_margin(margin, unit)

`margin` : | the new left margin in units of `unit`
`unit` : | the units for margin

The `set_left_margin`() method sets the left margin used by compositor.

### gtksourceview2.PrintCompositor.set_line_numbers_font_name

        def set_line_numbers_font_name(font_name)

`font_name` : | the name of the default font for the line numbers. or `None`.

The `set_line_numbers_font_name`() method sets the font for printing the line numbers. If `None` is supplied, the default font (i.e. the one being used for the text) will be used instead. `font_name` should be a string representation of a font description Pango can understand. (e.g. "Monospace 10"). See `pango.FontDescription`() for a description of the format of the string representation. This function cannot be called anymore after the first call to the `gtksourceview2.PrintCompositor.paginate`() method.

### gtksourceview2.PrintCompositor.set_print_footer

        def set_print_footer(print)

`print` : | `True` if you want the footer to be printed.

The `set_print_footer` method sets whether you want to print a footer in each page. The footer consists of three pieces of text and an optional line separator, configurable with `gtksourceview2.PrintCompositor.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.

This function cannot be called anymore after the first call to the `gtksourceview2.PrintCompositor.paginate`() method.

### gtksourceview2.PrintCompositor.set_print_header

        def set_print_header(print)

`print` : | `True` if you want the header to be printed.

The `set_print_header`() method sets whether you want to print a header in each page. The footer consists of three pieces of text and an optional line separator, configurable with `gtksourceview2.PrintCompositor.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.

This function cannot be called anymore after the first call to the `gtksourceview2.PrintCompositor.paginate`() method.

### gtksourceview2.PrintCompositor.set_print_line_numbers

        def set_print_line_numbers(interval)

`interval` : | interval for printed line numbers.

The `set_print_line_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).

Maximum accepted value for interval is 100.

This function cannot be called anymore after the first call to the `gtksourceview2.PrintCompositor.paginate`() method.

### gtksourceview2.PrintCompositor.set_right_margin

        def set_right_margin(margin, unit)

`margin` : | the new left margin in units of `unit`
`unit` : | the units for margin

The `set_right_margin`() method sets the right margin used by compositor.

### gtksourceview2.PrintCompositor.set_tab_width

        def set_tab_width(width)

`width` : | width of tab.

The `set_right_margin`() method returns the width of tabulation in characters for printed text.

### gtksourceview2.PrintCompositor.set_top_margin

        def set_top_margin(margin, unit)

`margin` : | the new left margin in units of `unit`
`unit` : | the units for margin

The `set_top_margin`() method sets the top margin used by compositor.

### gtksourceview2.PrintCompositor.set_wrap_mode

        def set_wrap_mode(wrap_mode)

`wrap_mode` : | one of gtk.WRAP_NONE, gtk.WRAP_CHAR, gtk.WRAP_WORD, gtk.WRAP_WORD_CHAR.

The `set_right_margin`() method sets the line wrapping mode for the printed text.

This function cannot be called anymore after the first call to the `gtksourceview2.PrintCompositor.paginate`() method.

## Functions

### gtksourceview2.print_compositor_new_from_view

        def gtksourceview2.print_compositor_new_from_view()

`wrap_mode` : | a `gtksourceview2.View` to get configuration from.
Returns : | a `gtksourceview2.PrintCompositor`.

The `print_compositor_new_from_view`() function creates a new print compositor that can be used to print the buffer associated with view. This constructor sets some configuration properties to make the printed output match view as much as possible. The properties set are "tab-width", "highlight-syntax", "wrap-mode", "body-font-name" and "print-line-numbers".

Prev |  | Next
gtksourceview2.Mark | Home | gtksourceview2.Style