:right-sidebar: True PrintCompositor =================================================================== .. currentmodule:: gi.repository.GtkSource .. class:: PrintCompositor(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` Compose a :obj:`~gi.repository.GtkSource.Buffer` for printing. The ``GtkSourcePrintCompositor`` object is used to compose a :obj:`~gi.repository.GtkSource.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. :obj:`~gi.repository.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 :obj:`~gi.repository.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. 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. wzxhzdk:0Monospace 10wzxhzdk:1). 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. wzxhzdk:0Monospace 10wzxhzdk:1). 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. wzxhzdk:0Monospace 10wzxhzdk:1). 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. wzxhzdk:0Monospace 10wzxhzdk:1). 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 The type of the None singleton. .. attribute:: props.buffer :type: ~gi.repository.GtkSource.Buffer The type of the None singleton. .. attribute:: props.footer_font_name :type: str The type of the None singleton. .. attribute:: props.header_font_name :type: str The type of the None singleton. .. attribute:: props.highlight_syntax :type: bool The type of the None singleton. .. attribute:: props.line_numbers_font_name :type: str The type of the None singleton. .. attribute:: props.n_pages :type: int The type of the None singleton. .. attribute:: props.print_footer :type: bool The type of the None singleton. .. attribute:: props.print_header :type: bool The type of the None singleton. .. attribute:: props.print_line_numbers :type: int The type of the None singleton. .. attribute:: props.tab_width :type: int The type of the None singleton. .. attribute:: props.wrap_mode :type: ~gi.repository.Gtk.WrapMode The type of the None singleton. Fields ------ .. rst-class:: interim-class .. class:: PrintCompositor :no-index: .. attribute:: parent_instance