Poppler.Page¶

Subclasses:: None

Methods¶

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

class	`free_annot_mapping` (list)
class	`free_form_field_mapping` (list)
class	`free_image_mapping` (list)
class	`free_link_mapping` (list)
class	`free_text_attributes` (list)
class	`selection_region_free` (region)
	`add_annot` (annot)
	`find_text` (text)
	`find_text_with_options` (text, options)
	`get_annot_mapping` ()
	`get_bounding_box` (rect)
	`get_crop_box` ()
	`get_duration` ()
	`get_form_field_mapping` ()
	`get_image` (image_id)
	`get_image_mapping` ()
	`get_index` ()
	`get_label` ()
	`get_link_mapping` ()
	`get_selected_region` (scale, style, selection)
	`get_selected_text` (style, selection)
	`get_selection_region` (scale, style, selection)
	`get_size` ()
	`get_text` ()
	`get_text_attributes` ()
	`get_text_attributes_for_area` (area)
	`get_text_for_area` (area)
	`get_text_layout` ()
	`get_text_layout_for_area` (area)
	`get_thumbnail` ()
	`get_thumbnail_size` ()
	`get_transition` ()
	`remove_annot` (annot)
	`render` (cairo)
	`render_for_printing` (cairo)
	`render_for_printing_with_options` (cairo, options)
	`render_full` (cairo, printing, flags)
	`render_selection` (cairo, selection, old_selection, style, glyph_color, background_color)
	`render_to_ps` (ps_file)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Name	Type	Flags	Short Description
`label`	`str`	r	The label of the page

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Class Details¶

class Poppler.Page(**kwargs)¶

Bases:: GObject.Object
Abstract:: No

classmethod free_annot_mapping(list)¶

Parameters:: list ([Poppler.AnnotMapping]) – A list of Poppler.AnnotMapping s

Frees a list of Poppler.AnnotMapping s allocated by Poppler.Page.get_annot_mapping(). It also unreferences the Poppler.Annot s that each mapping contains, so if you want to keep them around, you need to reference them with GObject.Object.ref().

classmethod free_form_field_mapping(list)¶

Parameters:: list ([Poppler.FormFieldMapping]) – A list of Poppler.FormFieldMapping s

Frees a list of Poppler.FormFieldMapping s allocated by Poppler.Page.get_form_field_mapping().

classmethod free_image_mapping(list)¶

Parameters:: list ([Poppler.ImageMapping]) – A list of Poppler.ImageMapping s

Frees a list of Poppler.ImageMapping s allocated by Poppler.Page.get_image_mapping().

classmethod free_link_mapping(list)¶

Parameters:: list ([Poppler.LinkMapping]) – A list of Poppler.LinkMapping s

Frees a list of Poppler.LinkMapping s allocated by Poppler.Page.get_link_mapping(). It also frees the Poppler.Action s that each mapping contains, so if you want to keep them around, you need to copy them with Poppler.Action.copy().

classmethod free_text_attributes(list)¶

Parameters:: list ([Poppler.TextAttributes]) – A list of Poppler.TextAttributes s

Frees a list of Poppler.TextAttributes s allocated by Poppler.Page.get_text_attributes().

New in version 0.18.

classmethod selection_region_free(region)¶

Parameters:: region ([Poppler.Rectangle]) – a GLib.List of Poppler.Rectangle

Frees region

Deprecated since version 0.16: Use only to free deprecated regions created by Poppler.Page.get_selection_region(). Regions created by Poppler.Page.get_selected_region() should be freed with cairo_region_destroy() instead.

add_annot(annot)¶

Parameters:: annot (Poppler.Annot) – a Poppler.Annot to add

Adds annotation annot to self.

New in version 0.16.

find_text(text)¶

Parameters:: text (str) – the text to search for (UTF-8 encoded)
Returns:: a GLib.List of Poppler.Rectangle,
Return type:: [Poppler.Rectangle]

Finds text in self with the default options (Poppler.FindFlags.DEFAULT) and returns a GLib.List of rectangles for each occurrence of the text on the page. The coordinates are in PDF points.

find_text_with_options(text, options)¶

Parameters:

text (str) – the text to search for (UTF-8 encoded)
options (Poppler.FindFlags) – find options

Returns:

a newly allocated list of newly allocated Poppler.Rectangle. Free with g_list_free_full() using Poppler.Rectangle.free().

Return type:

[Poppler.Rectangle]

Finds text in self with the given Poppler.FindFlags options and returns a GLib.List of rectangles for each occurrence of the text on the page. The coordinates are in PDF points.

When Poppler.FindFlags.MULTILINE is passed in options, matches may span more than one line. In this case, the returned list will contain one Poppler.Rectangle for each part of a match. The function Poppler.Rectangle.find_get_match_continued() will return True for all rectangles belonging to the same match, except for the last one. If a hyphen was ignored at the end of the part of the match, Poppler.Rectangle.find_get_ignored_hyphen() will return True for that rectangle.

Note that currently matches spanning more than two lines are not found. (This limitation may be lifted in a future version.)

Note also that currently finding multi-line matches backwards is not implemented; if you pass Poppler.FindFlags.BACKWARDS and Poppler.FindFlags.MULTILINE together, Poppler.FindFlags.MULTILINE will be ignored.

New in version 0.22.

get_annot_mapping()¶

Returns:: A GLib.List of Poppler.AnnotMapping
Return type:: [Poppler.AnnotMapping]

Returns a list of Poppler.AnnotMapping items that map from a location on self to a Poppler.Annot. This list must be freed with Poppler.Page.free_annot_mapping() when done.

get_bounding_box(rect)¶

Parameters:: rect (Poppler.Rectangle) –
Return type:: bool

get_crop_box()¶

Returns:: a Poppler.Rectangle to fill
Return type:: rect: Poppler.Rectangle

Retrurns the crop box of self

get_duration()¶

Returns:: duration in seconds of self or -1.
Return type:: float

Returns the duration of self

get_form_field_mapping()¶

Returns:: A GLib.List of Poppler.FormFieldMapping
Return type:: [Poppler.FormFieldMapping]

Returns a list of Poppler.FormFieldMapping items that map from a location on self to a form field. This list must be freed with Poppler.Page.free_form_field_mapping() when done.

get_image(image_id)¶

Parameters:: image_id (int) – The image identifier
Returns:: A cairo surface for the image
Return type:: cairo.Surface

Returns a cairo surface for the image of the self

get_image_mapping()¶

Returns:: A GLib.List of Poppler.ImageMapping
Return type:: [Poppler.ImageMapping]

Returns a list of Poppler.ImageMapping items that map from a location on self to an image of the page. This list must be freed with Poppler.Page.free_image_mapping() when done.

get_index()¶

Returns:: index value of self
Return type:: int

Returns the index of self

get_label()¶

Returns:: a new allocated string containing the label of self, or None if self doesn’t have a label
Return type:: str

Returns the label of self. Note that page labels and page indices might not coincide.

New in version 0.16.

get_link_mapping()¶

Returns:: A GLib.List of Poppler.LinkMapping
Return type:: [Poppler.LinkMapping]

Returns a list of Poppler.LinkMapping items that map from a location on self to a Poppler.Action. This list must be freed with Poppler.Page.free_link_mapping() when done.

get_selected_region(scale, style, selection)¶

Parameters:

scale (float) – scale specified as pixels per point
style (Poppler.SelectionStyle) – a Poppler.SelectionStyle
selection (Poppler.Rectangle) – start and end point of selection as a rectangle

Returns:

a cairo.Region

Return type:

cairo.Region

Returns a region containing the area that would be rendered by Poppler.Page.render_selection(). The returned region must be freed with cairo_region_destroy()

New in version 0.16.

get_selected_text(style, selection)¶

Parameters:

style (Poppler.SelectionStyle) – a Poppler.SelectionStyle
selection (Poppler.Rectangle) – the Poppler.Rectangle including the text

Returns:

a pointer to the contents of the selection as a string

Return type:

str

Retrieves the contents of the specified selection as text.

New in version 0.16.

get_selection_region(scale, style, selection)¶

Parameters:

scale (float) – scale specified as pixels per point
style (Poppler.SelectionStyle) – a Poppler.SelectionStyle
selection (Poppler.Rectangle) – start and end point of selection as a rectangle

Returns:

a GLib.List of Poppler.Rectangle

Return type:

[Poppler.Rectangle]

Returns a region containing the area that would be rendered by Poppler.Page.render_selection() as a GLib.List of Poppler.Rectangle. The returned list must be freed with Poppler.Page.selection_region_free().

Deprecated since version 0.16: Use Poppler.Page.get_selected_region() instead.

get_size()¶

Returns:

width:: return location for the width of self
height:: return location for the height of self

Return type:

(width: float, height: float)

Gets the size of self at the current scale and rotation.

get_text()¶

Returns:: a pointer to the text of the self as a string
Return type:: str

Retrieves the text of self.

New in version 0.16.

get_text_attributes()¶

Returns:: A GLib.List of Poppler.TextAttributes
Return type:: [Poppler.TextAttributes]

Obtains the attributes of the text as a GLib.List of Poppler.TextAttributes. This list must be freed with Poppler.Page.free_text_attributes() when done.

Each list element is a Poppler.TextAttributes struct where start_index and end_index indicates the range of text (as returned by Poppler.Page.get_text()) to which text attributes apply.

New in version 0.18.

get_text_attributes_for_area(area)¶

Parameters:: area (Poppler.Rectangle) – a Poppler.Rectangle
Returns:: A GLib.List of Poppler.TextAttributes
Return type:: [Poppler.TextAttributes]

Obtains the attributes of the text in area as a GLib.List of Poppler.TextAttributes. This list must be freed with Poppler.Page.free_text_attributes() when done.

Each list element is a Poppler.TextAttributes struct where start_index and end_index indicates the range of text (as returned by Poppler.Page.get_text_for_area()) to which text attributes apply.

New in version 0.26.

get_text_for_area(area)¶

Parameters:: area (Poppler.Rectangle) – a Poppler.Rectangle
Returns:: a pointer to the text as a string
Return type:: str

Retrieves the text of self contained in area.

New in version 0.26.

get_text_layout()¶

Returns:

True if the page contains text, False otherwise

rectangles:: return location for an array of Poppler.Rectangle

Return type:

(bool, rectangles: [Poppler.Rectangle])

Obtains the layout of the text as a list of Poppler.Rectangle This array must be freed with GLib.free() when done.

The position in the array represents an offset in the text returned by Poppler.Page.get_text()

New in version 0.16.

get_text_layout_for_area(area)¶

Parameters:

area (Poppler.Rectangle) – a Poppler.Rectangle

Returns:

True if the page contains text, False otherwise

rectangles:: return location for an array of Poppler.Rectangle

Return type:

(bool, rectangles: [Poppler.Rectangle])

Obtains the layout of the text contained in area as a list of Poppler.Rectangle This array must be freed with GLib.free() when done.

The position in the array represents an offset in the text returned by Poppler.Page.get_text_for_area()

New in version 0.26.

get_thumbnail()¶

Returns:: the tumbnail as a cairo.Surface or None if the document doesn’t have a thumbnail for this page.
Return type:: cairo.Surface

Get the embedded thumbnail for the specified page. If the document doesn’t have an embedded thumbnail for the page, this function returns None.

get_thumbnail_size()¶

Returns:

True, if self has a thumbnail associated with it.

width:: return location for width
height:: return location for height

Return type:

(bool, width: int, height: int)

Returns True if self has a thumbnail associated with it. It also fills in width and height with the width and height of the thumbnail. The values of width and height are not changed if no appropriate thumbnail exists.

get_transition()¶

Returns:: a Poppler.PageTransition or None.
Return type:: Poppler.PageTransition

Returns the transition effect of self

remove_annot(annot)¶

Parameters:: annot (Poppler.Annot) – a Poppler.Annot to remove

Removes annotation annot from self

New in version 0.22.

render(cairo)¶

Parameters:: cairo (cairo.Context) – cairo context to render to

Render the page to the given cairo context. This function is for rendering a page that will be displayed. If you want to render a page that will be printed use Poppler.Page.render_for_printing() instead. Please see the documentation for that function for the differences between rendering to the screen and rendering to a printer.

render_for_printing(cairo)¶

Parameters:: cairo (cairo.Context) – cairo context to render to

Render the page to the given cairo context for printing with Poppler.PrintFlags.ALL flags selected. If you want a different set of flags, use Poppler.Page.render_full() with printing True and the corresponding flags.

The difference between Poppler.Page.render() and this function is that some things get rendered differently between screens and printers:

PDF annotations get rendered according to their Poppler.AnnotFlag value. For example, Poppler.AnnotFlag.PRINT refers to whether an annotation is printed or not, whereas Poppler.AnnotFlag.NO_VIEW refers to whether an annotation is invisible when displaying to the screen.
PDF supports “hairlines” of width 0.0, which often get rendered as having a width of 1 device pixel. When displaying on a screen, Cairo may render such lines wide so that they are hard to see, and Poppler makes use of PDF’s Stroke Adjust graphics parameter to make the lines easier to see. However, when printing, Poppler is able to directly use a printer’s pixel size instead.
Some advanced features in PDF may require an image to be rasterized before sending off to a printer. This may produce raster images which exceed Cairo’s limits. The “printing” functions will detect this condition and try to down-scale the intermediate surfaces as appropriate.

render_for_printing_with_options(cairo, options)¶

Parameters:

cairo (cairo.Context) – cairo context to render to
options (Poppler.PrintFlags) – print options

Render the page to the given cairo context for printing with the specified options

See the documentation for Poppler.Page.render_for_printing() for the differences between rendering to the screen and rendering to a printer.

New in version 0.16.

Deprecated since version 25.02: Use Poppler.Page.render_full() instead.

render_full(cairo, printing, flags)¶

Parameters:

cairo (cairo.Context) – cairo context to render to
printing (bool) – cairo context to render to
flags (Poppler.RenderAnnotsFlags) – flags which allow to select which annotations to render

Render the page to the given cairo context, manually selecting which annotations should be displayed.

The printing parameter determines whether a page is rendered for printing or for displaying it on a screen. See the documentation for Poppler.Page.render_for_printing() for the differences between rendering to the screen and rendering to a printer.

New in version 25.02.

render_selection(cairo, selection, old_selection, style, glyph_color, background_color)¶

Parameters:

cairo (cairo.Context) – cairo context to render to
selection (Poppler.Rectangle) – start and end point of selection as a rectangle
old_selection (Poppler.Rectangle) – previous selection
style (Poppler.SelectionStyle) – a Poppler.SelectionStyle
glyph_color (Poppler.Color) – color to use for drawing glyphs
background_color (Poppler.Color) – color to use for the selection background

Render the selection specified by selection for self to the given cairo context. The selection will be rendered, using glyph_color for the glyphs and background_color for the selection background.

If non-None, old_selection specifies the selection that is already rendered to cairo, in which case this function will (some day) only render the changed part of the selection.

render_to_ps(ps_file)¶

Parameters:: ps_file (Poppler.PSFile) – the Poppler.PSFile to render to

Render the page on a postscript file

Property Details¶

Poppler.Page.props.label¶

Name:: label
Type:: str
Default Value:: None
Flags:: READABLE

The label of the page or None. See also Poppler.Page.get_label()