GtkSource.PrintCompositor¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`new` (buffer)
class	`new_from_view` (view)
	`draw_page` (context, page_nr)
	`get_body_font_name` ()
	`get_bottom_margin` (unit)
	`get_buffer` ()
	`get_footer_font_name` ()
	`get_header_font_name` ()
	`get_highlight_syntax` ()
	`get_left_margin` (unit)
	`get_line_numbers_font_name` ()
	`get_n_pages` ()
	`get_pagination_progress` ()
	`get_print_footer` ()
	`get_print_header` ()
	`get_print_line_numbers` ()
	`get_right_margin` (unit)
	`get_tab_width` ()
	`get_top_margin` (unit)
	`get_wrap_mode` ()
	`ignore_tag` (tag)
	`paginate` (context)
	`set_body_font_name` (font_name)
	`set_bottom_margin` (margin, unit)
	`set_footer_font_name` (font_name)
	`set_footer_format` (separator, left, center, right)
	`set_header_font_name` (font_name)
	`set_header_format` (separator, left, center, right)
	`set_highlight_syntax` (highlight)
	`set_left_margin` (margin, unit)
	`set_line_numbers_font_name` (font_name)
	`set_print_footer` (print_)
	`set_print_header` (print_)
	`set_print_line_numbers` (interval)
	`set_right_margin` (margin, unit)
	`set_tab_width` (width)
	`set_top_margin` (margin, unit)
	`set_wrap_mode` (wrap_mode)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Name	Type	Flags	Short Description
`body-font-name`	`str`	r/w/en
`buffer`	`GtkSource.Buffer`	r/w/co	The `GtkSource.Buffer` object to print
`footer-font-name`	`str`	r/w/en
`header-font-name`	`str`	r/w/en
`highlight-syntax`	`bool`	r/w/en
`line-numbers-font-name`	`str`	r/w/en
`n-pages`	`int`	r
`print-footer`	`bool`	r/w/en
`print-header`	`bool`	r/w/en
`print-line-numbers`	`int`	r/w/en
`tab-width`	`int`	r/w/en	Width of a tab character expressed in spaces
`wrap-mode`	`Gtk.WrapMode`	r/w/en

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent_instance	`GObject.Object`	r

Class Details¶

class GtkSource.PrintCompositor(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: GtkSource.PrintCompositorClass

Compose a [class`Buffer`] for printing.

The GtkSourcePrintCompositor object is used to compose a [class`Buffer`] for printing. You can set various configuration options to customize the printed output. GtkSourcePrintCompositor is designed to be used with the high-level printing API of gtk+, i.e. [class`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 [class`Gtk`.PageSetup] objects. If the specified layout margins are smaller than the “print margins”, the latter ones are used as a fallback by the GtkSourcePrintCompositor object, so that the printed area is not clipped.

classmethod new(buffer)¶

Parameters:: buffer (GtkSource.Buffer) – the GtkSource.Buffer to print.
Returns:: a new print compositor object.
Return type:: GtkSource.PrintCompositor

Creates a new print compositor that can be used to print buffer.

classmethod new_from_view(view)¶

Parameters:: view (GtkSource.View) – a GtkSource.View to get configuration from.
Returns:: a new print compositor object.
Return type:: GtkSource.PrintCompositor

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 [property`PrintCompositor`:py:data::tab-width<GtkSource.PrintCompositor.props.tab_width>], [property`PrintCompositor`:py:data::highlight-syntax<GtkSource.PrintCompositor.props.highlight_syntax>], [property`PrintCompositor`:py:data::wrap-mode<GtkSource.PrintCompositor.props.wrap_mode>], [property`PrintCompositor`:py:data::body-font-name<GtkSource.PrintCompositor.props.body_font_name>] and [property`PrintCompositor`:py:data::print-line-numbers<GtkSource.PrintCompositor.props.print_line_numbers>].

draw_page(context, page_nr)¶

Parameters:

context (Gtk.PrintContext) – the Gtk.PrintContext encapsulating the context information that is required when drawing the page for printing.
page_nr (int) – the number of the page to print.

Draw 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 [signal`Gtk`.PrintOperation::draw_page] signal as shown in the following example:

```c // Signal handler for the GtkPrintOperation::draw_page signal

static void draw_page (Gtk.PrintOperation *operation, Gtk.PrintContext *context, int page_nr, object user_data) { GtkSource.PrintCompositor *compositor;

compositor = GTK_SOURCE_PRINT_COMPOSITOR (user_data);

GtkSource.PrintCompositor.draw_page (compositor, context, page_nr); } `` ``python def on_draw_page( operation: Gtk.PrintOperation, context: Gtk.PrintContext, page_nr: int, compositor: GtkSource.PrintCompositor, ) -> None: “””Signal handler for draw-page that renders a single page.””” compositor.draw_page(context=context, page_nr=page_nr) ```

get_body_font_name()¶

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

Returns the name of the font used to print the text body.

The returned string must be freed with GLib.free().

get_bottom_margin(unit)¶

Parameters:: unit (Gtk.Unit) – the unit for the return value.
Returns:: the bottom margin.
Return type:: float

Gets the bottom margin in units of unit.

get_buffer()¶

Returns:: the GtkSource.Buffer associated with the compositor.
Return type:: GtkSource.Buffer

Gets the [class`Buffer`] associated with the compositor.

The returned object reference is owned by the compositor object and should not be unreferenced.

get_footer_font_name()¶

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

Returns the name of the font used to print the page footer.

The returned string must be freed with GLib.free().

get_header_font_name()¶

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

Returns the name of the font used to print the page header.

The returned string must be freed with GLib.free().

get_highlight_syntax()¶

Returns:: True if the printed output will be highlighted.
Return type:: bool

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.

get_left_margin(unit)¶

Parameters:: unit (Gtk.Unit) – the unit for the return value.
Returns:: the left margin
Return type:: float

Gets the left margin in units of unit.

get_line_numbers_font_name()¶

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

Returns the name of the font used to print line numbers on the left margin.

The returned string must be freed with GLib.free().

get_n_pages()¶

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

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

get_pagination_progress()¶

Returns:: a fraction from 0.0 to 1.0 inclusive.
Return type:: float

Returns the current fraction of the document pagination that has been completed.

get_print_footer()¶

Returns:: True if the footer is set to be printed.
Return type:: bool

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 [method`PrintCompositor`.set_footer_format].

get_print_header()¶

Returns:: True if the header is set to be printed.
Return type:: bool

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 [method`PrintCompositor`.set_header_format].

get_print_line_numbers()¶

Returns:: the interval of printed line numbers.
Return type:: int

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).

get_right_margin(unit)¶

Parameters:: unit (Gtk.Unit) – the unit for the return value.
Returns:: the right margin.
Return type:: float

Gets the right margin in units of unit.

get_tab_width()¶

Returns:: width of tab.
Return type:: int

Returns the width of tabulation in characters for printed text.

get_top_margin(unit)¶

Parameters:: unit (Gtk.Unit) – the unit for the return value.
Returns:: the top margin.
Return type:: float

Gets the top margin in units of unit.

get_wrap_mode()¶

Returns:: the line wrap mode.
Return type:: Gtk.WrapMode

Gets the line wrapping mode for the printed text.

ignore_tag(tag)¶

Parameters:: tag (Gtk.TextTag) – a Gtk.TextTag

Specifies a tag whose style should be ignored when compositing the document to the printable page.

New in version 5.2.

paginate(context)¶

Parameters:: context (Gtk.PrintContext) – the Gtk.PrintContext whose parameters (e.g. paper size, print margins, etc.) are used by the the self to paginate the document.
Returns:: True if the document has been completely paginated, False otherwise.
Return type:: bool

Paginate the document associated with the self.

In order to support non-blocking pagination, document is paginated in small chunks. Each time [method`PrintCompositor`.paginate] is invoked, a chunk of the document is paginated. To paginate the entire document, [method`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 [signal`Gtk`.PrintOperation::paginate] signal, as shown in the following example:

```c // Signal handler for the Gtk.PrintOperation ::paginate signal

static bool paginate (Gtk.PrintOperation *operation, Gtk.PrintContext *context, object user_data) { GtkSource.PrintCompositor *compositor;

compositor = GTK_SOURCE_PRINT_COMPOSITOR (user_data);

if (GtkSource.PrintCompositor.paginate (compositor, context)) { int n_pages;

n_pages = GtkSource.PrintCompositor.get_n_pages (compositor); Gtk.PrintOperation.set_n_pages (operation, n_pages);

return True; }

return False; } `` ``python def on_paginate( operation: Gtk.PrintOperation, context: Gtk.PrintContext, compositor: GtkSource.PrintCompositor, ) -> bool: if compositor.paginate(context=context): n_pages = compositor.get_n_pages() operation.set_n_pages(n_pages=n_pages) return True return False ```

If you don’t need to do pagination in chunks, you can simply do it all in the [signal`Gtk`.PrintOperation::begin-print] handler, and set the number of pages from there, like in the following example:

```c // Signal handler for the Gtk.PrintOperation ::begin-print signal

static void begin_print (Gtk.PrintOperation *operation, Gtk.PrintContext *context, object user_data) { GtkSource.PrintCompositor *compositor; int n_pages;

compositor = GTK_SOURCE_PRINT_COMPOSITOR (user_data);

while (!:obj:GtkSource.PrintCompositor.paginate (compositor, context));

n_pages = GtkSource.PrintCompositor.get_n_pages (compositor); Gtk.PrintOperation.set_n_pages (operation, n_pages); } `` ``python def on_begin_print( operation: Gtk.PrintOperation, context: Gtk.PrintContext, compositor: GtkSource.PrintCompositor, ) -> None: # Paginate until complete while not compositor.paginate(context=context): pass

n_pages = compositor.get_n_pages() operation.set_n_pages(n_pages=n_pages) ```

set_body_font_name(font_name)¶

Parameters:: font_name (str) – the name of the default font for the body text.

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 [func`Pango`.FontDescription.from_string] for a description of the format of the string representation.

This function cannot be called anymore after the first call to the [method`PrintCompositor`.paginate] function.

set_bottom_margin(margin, unit)¶

Parameters:

margin (float) – the new bottom margin in units of unit.
unit (Gtk.Unit) – the units for margin.

Sets the bottom margin used by self.

set_footer_font_name(font_name)¶

Parameters:: font_name (str or None) – the name of the font for the footer text, or None.

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 [func`Pango`.FontDescription.from_string] for a description of the format of the string representation.

This function cannot be called anymore after the first call to the [method`PrintCompositor`.paginate] function.

set_footer_format(separator, left, center, right)¶

Parameters:

separator (bool) – True if you want a separator line to be printed.
left (str or None) – a format string to print on the left of the footer.
center (str or None) – a format string to print on the center of the footer.
right (str or None) – a format string to print on the right of the footer.

See [method`PrintCompositor`.set_header_format] for more information about the parameters.

set_header_font_name(font_name)¶

Parameters:: font_name (str or None) – the name of the font for header text, or None.

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 [func`Pango`.FontDescription.from_string] for a description of the format of the string representation.

This function cannot be called anymore after the first call to the [method`PrintCompositor`.paginate] function.

set_header_format(separator, left, center, right)¶

Parameters:

separator (bool) – True if you want a separator line to be printed.
left (str or None) – a format string to print on the left of the header.
center (str or None) – a format string to print on the center of the header.
right (str or None) – a format string to print on the right of the header.

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. A subset of strftime() codes are accepted, see [method`GLib`.DateTime.format] for more details on the accepted format specifiers. Additionally the following format specifiers are accepted:

#N: the page number
#Q: 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 [method`PrintCompositor`.set_print_header].

This function cannot be called anymore after the first call to the [method`PrintCompositor`.paginate] function.

set_highlight_syntax(highlight)¶

Parameters:: highlight (bool) – whether syntax should be highlighted.

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 [method`PrintCompositor`.paginate] function.

set_left_margin(margin, unit)¶

Parameters:

margin (float) – the new left margin in units of unit.
unit (Gtk.Unit) – the units for margin.

Sets the left margin used by self.

set_line_numbers_font_name(font_name)¶

Parameters:: font_name (str or None) – the name of the font for line numbers, or None.

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.

font_name should be a string representation of a font description Pango can understand. (e.g. “Monospace 10”). See [func`Pango`.FontDescription.from_string] for a description of the format of the string representation.

This function cannot be called anymore after the first call to the [method`PrintCompositor`.paginate] function.

set_print_footer(print_)¶

Parameters:: print (bool) – True if you want the footer to be printed.

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 [method`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 [method`PrintCompositor`.paginate] function.

set_print_header(print_)¶

Parameters:: print (bool) – True if you want the header to be printed.

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

The header consists of three pieces of text and an optional line separator, configurable with [method`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 [method`PrintCompositor`.paginate] function.

set_print_line_numbers(interval)¶

Parameters:: interval (int) – interval for printed line numbers.

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 [method`PrintCompositor`.paginate] function.

set_right_margin(margin, unit)¶

Parameters:

margin (float) – the new right margin in units of unit.
unit (Gtk.Unit) – the units for margin.

Sets the right margin used by self.

set_tab_width(width)¶

Parameters:: width (int) – width of tab in characters.

Sets the width of tabulation in characters for printed text.

This function cannot be called anymore after the first call to the [method`PrintCompositor`.paginate] function.

set_top_margin(margin, unit)¶

Parameters:

margin (float) – the new top margin in units of unit
unit (Gtk.Unit) – the units for margin

Sets the top margin used by self.

set_wrap_mode(wrap_mode)¶

Parameters:: wrap_mode (Gtk.WrapMode) – a Gtk.WrapMode.

Sets the line wrapping mode for the printed text.

This function cannot be called anymore after the first call to the [method`PrintCompositor`.paginate] function.

Property Details¶

GtkSource.PrintCompositor.props.body_font_name¶

Name:: body-font-name
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

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 [func`Pango`.FontDescription.from_string] for a description of the format of the string representation.

The value of this property cannot be changed anymore after the first call to the [method`PrintCompositor`.paginate] function.

GtkSource.PrintCompositor.props.buffer¶

Name:: buffer
Type:: GtkSource.Buffer
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The [class`Buffer`] object to print.

GtkSource.PrintCompositor.props.footer_font_name¶

Name:: footer-font-name
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

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 [func`Pango`.FontDescription.from_string] for a description of the format of the string representation.

The value of this property cannot be changed anymore after the first call to the [method`PrintCompositor`.paginate] function.

GtkSource.PrintCompositor.props.header_font_name¶

Name:: header-font-name
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Name of the font used to print page header. 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 [func`Pango`.FontDescription.from_string] for a description of the format of the string representation.

The value of this property cannot be changed anymore after the first call to the [method`PrintCompositor`.paginate] function.

GtkSource.PrintCompositor.props.highlight_syntax¶

Name:: highlight-syntax
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether to print the document with highlighted syntax.

The value of this property cannot be changed anymore after the first call to the [method`PrintCompositor`.paginate] function.

GtkSource.PrintCompositor.props.line_numbers_font_name¶

Name:: line-numbers-font-name
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Name of the font used to print line numbers on the left margin. 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 [func`Pango`.FontDescription.from_string] for a description of the format of the string representation.

The value of this property cannot be changed anymore after the first call to the [method`PrintCompositor`.paginate] function.

GtkSource.PrintCompositor.props.n_pages¶

Name:: n-pages
Type:: int
Default Value:: -1
Flags:: READABLE

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

GtkSource.PrintCompositor.props.print_footer¶

Name:: print-footer
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

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 [method`PrintCompositor`.paginate] function.

GtkSource.PrintCompositor.props.print_header¶

Name:: print-header
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

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 [method`PrintCompositor`.paginate] function.

GtkSource.PrintCompositor.props.print_line_numbers¶

Name:: print-line-numbers
Type:: int
Default Value:: 1
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

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 [method`PrintCompositor`.paginate] function.

GtkSource.PrintCompositor.props.tab_width¶

Name:: tab-width
Type:: int
Default Value:: 8
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Width of a tab character expressed in spaces.

The value of this property cannot be changed anymore after the first call to the [method`PrintCompositor`.paginate] function.

GtkSource.PrintCompositor.props.wrap_mode¶

Name:: wrap-mode
Type:: Gtk.WrapMode
Default Value:: Gtk.WrapMode.NONE
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

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 [method`PrintCompositor`.paginate] function.