:right-sidebar: True
PrintCompositor
===================================================================
.. currentmodule:: gi.repository.GtkSource
.. class:: PrintCompositor(**properties: ~typing.Any)
:no-contents-entry:
Superclasses: :class:`~gi.repository.GObject.Object`
:Constructors:
::
PrintCompositor(**properties)
new(buffer:GtkSource.Buffer) -> GtkSource.PrintCompositor
new_from_view(view:GtkSource.View) -> GtkSource.PrintCompositor
Constructors
------------
.. rst-class:: interim-class
.. class:: PrintCompositor
:no-index:
.. classmethod:: new(buffer: ~gi.repository.GtkSource.Buffer) -> ~gi.repository.GtkSource.PrintCompositor
Creates a new print compositor that can be used to print ``buffer``.
:param buffer: the :obj:`~gi.repository.GtkSource.Buffer` to print.
.. classmethod:: new_from_view(view: ~gi.repository.GtkSource.View) -> ~gi.repository.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
:obj:`~gi.repository.GtkSource.PrintCompositor.props.tab_width`, :obj:`~gi.repository.GtkSource.PrintCompositor.props.highlight_syntax`,
:obj:`~gi.repository.GtkSource.PrintCompositor.props.wrap_mode`, :obj:`~gi.repository.GtkSource.PrintCompositor.props.body_font_name` and
:obj:`~gi.repository.GtkSource.PrintCompositor.props.print_line_numbers`.
:param view: a :obj:`~gi.repository.GtkSource.View` to get configuration from.
Methods
-------
.. rst-class:: interim-class
.. class:: PrintCompositor
:no-index:
.. method:: draw_page(context: ~gi.repository.Gtk.PrintContext, page_nr: int) -> None
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 :obj:`~gi.repository.Gtk.PrintOperation.signals.draw_page` signal
as shown in the following example:
.. code-block:: c
:dedent:
// Signal handler for the GtkPrintOperation::draw_page signal
static void
draw_page (GtkPrintOperation *operation,
GtkPrintContext *context,
gint page_nr,
gpointer user_data)
{
GtkSourcePrintCompositor *compositor;
compositor = GTK_SOURCE_PRINT_COMPOSITOR (user_data);
gtk_source_print_compositor_draw_page (compositor,
context,
page_nr);
}
:param context: the :obj:`~gi.repository.Gtk.PrintContext` encapsulating the context information that is required when
drawing the page for printing.
:param page_nr: the number of the page to print.
.. method:: get_body_font_name() -> str
Returns the name of the font used to print the text body.
The returned string must be freed with :func:`~gi.repository.GLib.free`.
.. method:: get_bottom_margin(unit: ~gi.repository.Gtk.Unit) -> float
Gets the bottom margin in units of ``unit``.
:param unit: the unit for the return value.
.. method:: get_buffer() -> ~gi.repository.GtkSource.Buffer
Gets the :obj:`~gi.repository.GtkSource.Buffer` associated with the compositor.
The returned object reference is owned by the compositor object and
should not be unreferenced.
.. method:: get_footer_font_name() -> str
Returns the name of the font used to print the page footer.
The returned string must be freed with :func:`~gi.repository.GLib.free`.
.. method:: get_header_font_name() -> str
Returns the name of the font used to print the page header.
The returned string must be freed with :func:`~gi.repository.GLib.free`.
.. method:: get_highlight_syntax() -> 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.
.. method:: get_left_margin(unit: ~gi.repository.Gtk.Unit) -> float
Gets the left margin in units of ``unit``.
:param unit: the unit for the return value.
.. method:: get_line_numbers_font_name() -> str
Returns the name of the font used to print line numbers on the left margin.
The returned string must be freed with :func:`~gi.repository.GLib.free`.
.. method:: get_n_pages() -> int
Returns the number of pages in the document or -1 if the
document has not been completely paginated.
.. method:: get_pagination_progress() -> float
Returns the current fraction of the document pagination that has been completed.
.. method:: get_print_footer() -> bool
Determines if a footer is set to be printed for each page.
A footer will be printed if this function returns :const:`True`
**and** some format strings have been specified
with :obj:`~gi.repository.PrintCompositor.set_footer_format`.
.. method:: get_print_header() -> bool
Determines if a header is set to be printed for each page.
A header will be printed if this function returns :const:`True`
**and** some format strings have been specified
with :obj:`~gi.repository.PrintCompositor.set_header_format`.
.. method:: get_print_line_numbers() -> 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).
.. method:: get_right_margin(unit: ~gi.repository.Gtk.Unit) -> float
Gets the right margin in units of ``unit``.
:param unit: the unit for the return value.
.. method:: get_tab_width() -> int
Returns the width of tabulation in characters for printed text.
.. method:: get_top_margin(unit: ~gi.repository.Gtk.Unit) -> float
Gets the top margin in units of ``unit``.
:param unit: the unit for the return value.
.. method:: get_wrap_mode() -> ~gi.repository.Gtk.WrapMode
Gets the line wrapping mode for the printed text.
.. method:: ignore_tag(tag: ~gi.repository.Gtk.TextTag) -> None
Specifies a tag whose style should be ignored when compositing the
document to the printable page.
.. versionadded:: 5.2
:param tag: a :obj:`~gi.repository.Gtk.TextTag`
.. method:: paginate(context: ~gi.repository.Gtk.PrintContext) -> bool
Paginate the document associated with the ``compositor``.
In order to support non-blocking pagination, document is paginated in small chunks.
Each time :obj:`~gi.repository.PrintCompositor.paginate` is invoked, a chunk of the document
is paginated. To paginate the entire document, :obj:`~gi.repository.PrintCompositor.paginate`
must be invoked multiple times.
It returns :const:`True` if the document has been completely paginated, otherwise it returns :const:`False`.
This method has been designed to be invoked in the handler of the :obj:`~gi.repository.Gtk.PrintOperation.signals.paginate` signal,
as shown in the following example:
.. code-block:: c
:dedent:
// Signal handler for the GtkPrintOperation::paginate signal
static gboolean
paginate (GtkPrintOperation *operation,
GtkPrintContext *context,
gpointer user_data)
{
GtkSourcePrintCompositor *compositor;
compositor = GTK_SOURCE_PRINT_COMPOSITOR (user_data);
if (gtk_source_print_compositor_paginate (compositor, context))
{
gint n_pages;
n_pages = gtk_source_print_compositor_get_n_pages (compositor);
gtk_print_operation_set_n_pages (operation, n_pages);
return TRUE;
}
return FALSE;
}
If you don't need to do pagination in chunks, you can simply do it all in the
:obj:`~gi.repository.Gtk.PrintOperation.signals.begin_print` handler, and set the number of pages from there, like
in the following example:
.. code-block:: c
:dedent:
// Signal handler for the GtkPrintOperation::begin-print signal
static void
begin_print (GtkPrintOperation *operation,
GtkPrintContext *context,
gpointer user_data)
{
GtkSourcePrintCompositor *compositor;
gint n_pages;
compositor = GTK_SOURCE_PRINT_COMPOSITOR (user_data);
while (!gtk_source_print_compositor_paginate (compositor, context));
n_pages = gtk_source_print_compositor_get_n_pages (compositor);
gtk_print_operation_set_n_pages (operation, n_pages);
}
:param context: the :obj:`~gi.repository.Gtk.PrintContext` whose parameters (e.g. paper size, print margins, etc.)
are used by the the ``compositor`` to paginate the document.
.. method:: set_body_font_name(font_name: str) -> None
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 :obj:`~gi.repository.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
:obj:`~gi.repository.PrintCompositor.paginate` function.
:param font_name: the name of the default font for the body text.
.. method:: set_bottom_margin(margin: float, unit: ~gi.repository.Gtk.Unit) -> None
Sets the bottom margin used by ``compositor``.
:param margin: the new bottom margin in units of ``unit``.
:param unit: the units for ``margin``.
.. method:: set_footer_font_name(font_name: str | None = None) -> None
Sets the font for printing the page footer.
If :const:`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 :obj:`~gi.repository.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
:obj:`~gi.repository.PrintCompositor.paginate` function.
:param font_name: the name of the font for the footer text, or :const:`None`.
.. method:: set_footer_format(separator: bool, left: str | None = None, center: str | None = None, right: str | None = None) -> None
See :obj:`~gi.repository.PrintCompositor.set_header_format` for more information
about the parameters.
:param separator: :const:`True` if you want a separator line to be printed.
:param left: a format string to print on the left of the footer.
:param center: a format string to print on the center of the footer.
:param right: a format string to print on the right of the footer.
.. method:: set_header_font_name(font_name: str | None = None) -> None
Sets the font for printing the page header.
If :const:`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 :obj:`~gi.repository.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
:obj:`~gi.repository.PrintCompositor.paginate` function.
:param font_name: the name of the font for header text, or :const:`None`.
.. method:: set_header_format(separator: bool, left: str | None = None, center: str | None = None, right: str | None = None) -> None
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 :obj:`~gi.repository.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 :const:`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 :obj:`~gi.repository.PrintCompositor.set_print_header`.
This function cannot be called anymore after the first call to the
:obj:`~gi.repository.PrintCompositor.paginate` function.
:param separator: :const:`True` if you want a separator line to be printed.
:param left: a format string to print on the left of the header.
:param center: a format string to print on the center of the header.
:param right: a format string to print on the right of the header.
.. method:: set_highlight_syntax(highlight: bool) -> None
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
:obj:`~gi.repository.PrintCompositor.paginate` function.
:param highlight: whether syntax should be highlighted.
.. method:: set_left_margin(margin: float, unit: ~gi.repository.Gtk.Unit) -> None
Sets the left margin used by ``compositor``.
:param margin: the new left margin in units of ``unit``.
:param unit: the units for ``margin``.
.. method:: set_line_numbers_font_name(font_name: str | None = None) -> None
Sets the font for printing line numbers on the left margin.
If :const:`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 :obj:`~gi.repository.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
:obj:`~gi.repository.PrintCompositor.paginate` function.
:param font_name: the name of the font for line numbers, or :const:`None`.
.. method:: set_print_footer(print_: bool) -> None
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
:obj:`~gi.repository.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
:obj:`~gi.repository.PrintCompositor.paginate` function.
:param print_:
.. method:: set_print_header(print_: bool) -> None
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 :obj:`~gi.repository.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
:obj:`~gi.repository.PrintCompositor.paginate` function.
:param print_:
.. method:: set_print_line_numbers(interval: int) -> None
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
:obj:`~gi.repository.PrintCompositor.paginate` function.
:param interval: interval for printed line numbers.
.. method:: set_right_margin(margin: float, unit: ~gi.repository.Gtk.Unit) -> None
Sets the right margin used by ``compositor``.
:param margin: the new right margin in units of ``unit``.
:param unit: the units for ``margin``.
.. method:: set_tab_width(width: int) -> None
Sets the width of tabulation in characters for printed text.
This function cannot be called anymore after the first call to the
:obj:`~gi.repository.PrintCompositor.paginate` function.
:param width: width of tab in characters.
.. method:: set_top_margin(margin: float, unit: ~gi.repository.Gtk.Unit) -> None
Sets the top margin used by ``compositor``.
:param margin: the new top margin in units of ``unit``
:param unit: the units for ``margin``
.. method:: set_wrap_mode(wrap_mode: ~gi.repository.Gtk.WrapMode) -> None
Sets the line wrapping mode for the printed text.
This function cannot be called anymore after the first call to the
:obj:`~gi.repository.PrintCompositor.paginate` function.
:param wrap_mode: a :obj:`~gi.repository.Gtk.WrapMode`.
Properties
----------
.. rst-class:: interim-class
.. class:: PrintCompositor
:no-index:
.. attribute:: props.body_font_name
:type: str
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 :obj:`~gi.repository.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 :obj:`~gi.repository.PrintCompositor.paginate` function.
.. attribute:: props.buffer
:type: ~gi.repository.GtkSource.Buffer
The :obj:`~gi.repository.GtkSource.Buffer` object to print.
.. attribute:: props.footer_font_name
:type: str
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 :obj:`~gi.repository.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 :obj:`~gi.repository.PrintCompositor.paginate` function.
.. attribute:: props.header_font_name
:type: str
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 :obj:`~gi.repository.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 :obj:`~gi.repository.PrintCompositor.paginate` function.
.. attribute:: props.highlight_syntax
:type: bool
Whether to print the document with highlighted syntax.
The value of this property cannot be changed anymore after the first
call to the :obj:`~gi.repository.PrintCompositor.paginate` function.
.. attribute:: props.line_numbers_font_name
:type: str
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 :obj:`~gi.repository.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 :obj:`~gi.repository.PrintCompositor.paginate` function.
.. attribute:: props.n_pages
:type: int
The number of pages in the document or -1 if the
document has not been completely paginated.
.. attribute:: props.print_footer
:type: bool
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 :obj:`~gi.repository.PrintCompositor.paginate` function.
.. attribute:: props.print_header
:type: bool
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 :obj:`~gi.repository.PrintCompositor.paginate` function.
.. attribute:: props.print_line_numbers
:type: int
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 :obj:`~gi.repository.PrintCompositor.paginate` function.
.. attribute:: props.tab_width
:type: int
Width of a tab character expressed in spaces.
The value of this property cannot be changed anymore after the first
call to the :obj:`~gi.repository.PrintCompositor.paginate` function.
.. attribute:: props.wrap_mode
:type: ~gi.repository.Gtk.WrapMode
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 :obj:`~gi.repository.PrintCompositor.paginate` function.
Fields
------
.. rst-class:: interim-class
.. class:: PrintCompositor
:no-index:
.. attribute:: parent_instance