PapersDocument.Document¶

Subclasses:: None

Methods¶

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

class	`factory_add_filters` (dialog, document)
class	`factory_get_document` (uri)
class	`factory_get_document_for_fd` (fd, mime_type, flags)
class	`factory_get_document_full` (uri, flags)
class	`misc_format_datetime` (dt)
class	`misc_get_pointer_position` (widget)
class	`misc_get_widget_dpi` (widget)
class	`misc_pixbuf_from_surface` (surface)
class	`misc_surface_from_pixbuf` (pixbuf)
class	`misc_surface_rotate_and_scale` (surface, dest_width, dest_height, dest_rotation)
class	`misc_texture_from_surface` (surface)
	`check_dimensions` ()
	`doc_mutex_lock` ()
	`doc_mutex_unlock` ()
	`find_page_by_label` (page_label)
	`get_backend_info` (info)
	`get_info` ()
	`get_max_label_len` ()
	`get_max_page_size` ()
	`get_min_page_size` ()
	`get_modified` ()
	`get_n_pages` ()
	`get_page` (index)
	`get_page_label` (page_index)
	`get_page_size` (page_index)
	`get_size` ()
	`get_thumbnail` (rc)
	`get_thumbnail_surface` (rc)
	`get_title` ()
	`get_uri` ()
	`has_text_page_labels` ()
	`is_page_size_uniform` ()
	`load` (uri)
	`load_fd` (fd, flags)
	`load_full` (uri, flags)
	`render` (rc)
	`save` (uri)
	`set_modified` (modified)

Virtual Methods¶

Inherited:: GObject.Object (7)

	`do_get_backend_info` (info)
	`do_get_info` ()
	`do_get_n_pages` ()
	`do_get_page` (index)
	`do_get_page_label` (page)
	`do_get_page_size` (page_index)
	`do_get_thumbnail` (rc)
	`do_get_thumbnail_surface` (rc)
	`do_load` (uri)
	`do_load_fd` (fd, flags)
	`do_load_gfile` (file, flags, cancellable)
	`do_load_stream` (stream, flags, cancellable)
	`do_render` (rc)
	`do_save` (uri)

Properties¶

Name	Type	Flags	Short Description
`modified`	`bool`	r/w	Whether the document has been modified

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent_instance	`GObject.Object`	r

Class Details¶

class PapersDocument.Document(**kwargs)¶

Bases:: GObject.Object
Abstract:: Yes
Structure:: PapersDocument.DocumentClass

classmethod factory_add_filters(dialog, document)¶

Parameters:

dialog (Gtk.FileDialog) – a Gtk.FileDialog
document (PapersDocument.Document or None) – a PapersDocument.Document, or None

Adds some file filters to dialog.

Always add a “All documents” format.

If document is not None, adds a Gtk.FileFilter for document's MIME type.

If document is None, adds a Gtk.FileFilter for each document type that papers can handle.

classmethod factory_get_document(uri)¶

Parameters:: uri (str) – an URI
Raises:: GLib.Error
Returns:: a new PapersDocument.Document, or None
Return type:: PapersDocument.Document

Creates a PapersDocument.Document for the document at uri; or, if no backend handling the document’s type is found, or an error occurred on opening the document, returns None and fills in error. If the document is encrypted, it is returned but also error is set to PapersDocument.DocumentError.ENCRYPTED.

classmethod factory_get_document_for_fd(fd, mime_type, flags)¶

Parameters:

fd (int) – a file descriptor
mime_type (str) – the mime type
flags (PapersDocument.DocumentLoadFlags) – flags from PapersDocument.DocumentLoadFlags

Raises:

GLib.Error

Returns:

a new PapersDocument.Document, or None

Return type:

PapersDocument.Document

Synchronously creates a PapersDocument.Document for the document from fd using the backend for loading documents of type mime_type; or, if the backend does not support loading from file descriptors, or an error occurred on opening the document, returns None and fills in error. If the document is encrypted, it is returned but also error is set to PapersDocument.DocumentError.ENCRYPTED.

If the mime type cannot be inferred from the file descriptor, and mime_type is None, an error is returned.

Note that this function takes ownership of fd; you must not ever operate on it again. It will be closed automatically if the document is destroyed, or if this function returns None.

New in version 42.0.

classmethod factory_get_document_full(uri, flags)¶

Parameters:

uri (str) – an URI
flags (PapersDocument.DocumentLoadFlags) – flags from PapersDocument.DocumentLoadFlags

Raises:

GLib.Error

Returns:

a new PapersDocument.Document, or None

Return type:

PapersDocument.Document

Creates a PapersDocument.Document for the document at uri; or, if no backend handling the document’s type is found, or an error occurred on opening the document, returns None and fills in error. If the document is encrypted, it is returned but also error is set to PapersDocument.DocumentError.ENCRYPTED.

classmethod misc_format_datetime(dt)¶

Parameters:: dt (GLib.DateTime) – a GLib.DateTime
Returns:: a new allocated string or None in the case that there was an error (such as a format specifier not being supported in the current locale). The string should be freed with GLib.free().
Return type:: str

Determine the preferred date and time representation for the current locale for dt.

New in version 3.38.

classmethod misc_get_pointer_position(widget)¶

Parameters:

widget (Gtk.Widget) – a Gtk.Widget

Returns:

x:: the pointer’s “x” position, or -1 if the position is not available
y:: the pointer’s “y” position, or -1 if the position is not available

Return type:

(bool, x: int, y: int)

Get the pointer’s x and y position relative to widget.

classmethod misc_get_widget_dpi(widget)¶

Parameters:: widget (Gtk.Widget) – a Gtk.Widget
Returns:: DPI as float
Return type:: float

Returns sensible guess for DPI of monitor on which given widget has been realized. If HiDPI display, use 192, else 96. Returns 96 as fallback value.

classmethod misc_pixbuf_from_surface(surface)¶

Parameters:: surface (cairo.Surface) – a cairo.Surface
Returns:: a GdkPixbuf.Pixbuf
Return type:: GdkPixbuf.Pixbuf

classmethod misc_surface_from_pixbuf(pixbuf)¶

Parameters:: pixbuf (GdkPixbuf.Pixbuf) –
Return type:: cairo.Surface

classmethod misc_surface_rotate_and_scale(surface, dest_width, dest_height, dest_rotation)¶

Parameters:

surface (cairo.Surface) –
dest_width (int) –
dest_height (int) –
dest_rotation (int) –

Return type:

cairo.Surface

classmethod misc_texture_from_surface(surface)¶

Parameters:: surface (cairo.Surface) – a cairo.Surface
Returns:: The converted Gdk.Texture
Return type:: Gdk.Texture

Convert a cairo.Surface to Gdk.Texture object.

check_dimensions()¶

Return type:: bool

doc_mutex_lock()¶

doc_mutex_unlock()¶

find_page_by_label(page_label)¶

Parameters:

page_label (str) – the page label

Returns:

True iff the page index is found

page_index:: the output page index

Return type:

(bool, page_index: int)

get_backend_info(info)¶

Parameters:: info (PapersDocument.DocumentBackendInfo) –
Return type:: bool

get_info()¶

Returns:: a PapersDocument.DocumentInfo
Return type:: PapersDocument.DocumentInfo

Returns the PapersDocument.DocumentInfo for the document.

get_max_label_len()¶

Return type:: int

get_max_page_size()¶

Returns:

width:: max page width
height:: max page height

Return type:

(width: float, height: float)

get_min_page_size()¶

Returns:

width:: min page width
height:: min page height

Return type:

(width: float, height: float)

get_modified()¶

Returns:

True iff the document has been modified.

You can monitor changes to the modification state by connecting to the notify::modified signal on self.

Return type:

bool

New in version 3.28.

get_n_pages()¶

Return type:: int

get_page(index)¶

Parameters:: index (int) – index of page
Returns:: Newly created PapersDocument.Page for the given index.
Return type:: PapersDocument.Page

get_page_label(page_index)¶

Parameters:: page_index (int) –
Return type:: str

get_page_size(page_index)¶

Parameters:

page_index (int) – index of page

Returns:

width:: return location for the width of the page, or None
height:: return location for the height of the page, or None

Return type:

(width: float, height: float)

get_size()¶

Return type:: int

get_thumbnail(rc)¶

Parameters:: rc (PapersDocument.RenderContext) – an PapersDocument.RenderContext
Returns:: a GdkPixbuf.Pixbuf
Return type:: GdkPixbuf.Pixbuf

get_thumbnail_surface(rc)¶

Parameters:: rc (PapersDocument.RenderContext) – an PapersDocument.RenderContext
Returns:: a cairo.Surface
Return type:: cairo.Surface

New in version 3.14.

get_title()¶

Return type:: str

get_uri()¶

Return type:: str

has_text_page_labels()¶

Return type:: bool

is_page_size_uniform()¶

Return type:: bool

load(uri)¶

Parameters:: uri (str) – the document’s URI
Raises:: GLib.Error
Returns:: True on success, or False on failure.
Return type:: bool

Loads self from uri.

On failure, False is returned and error is filled in. If the document is encrypted, PPS_DEFINE_ERROR_ENCRYPTED is returned. If the backend cannot load the specific document, PapersDocument.DocumentError.INVALID is returned. If the backend does not support the format for the document’s contents, PapersDocument.DocumentError.UNSUPPORTED_CONTENT is returned. Other errors are possible too, depending on the backend used to load the document and the URI, e.g. GLib.IOError, GLib.FileError, and GLib.ConvertError.

load_fd(fd, flags)¶

Parameters:

fd (int) – a file descriptor
flags (PapersDocument.DocumentLoadFlags) – flags from PapersDocument.DocumentLoadFlags

Raises:

GLib.Error

Returns:

True if loading succeeded, or False on error with error filled in

Return type:

bool

Synchronously loads the document from fd, which must refer to a regular file.

Note that this function takes ownership of fd; you must not ever operate on it again. It will be closed automatically if the document is destroyed, or if this function returns None.

See PapersDocument.Document.load() for more information.

New in version 42.0.

load_full(uri, flags)¶

Parameters:

uri (str) – the document’s URI
flags (PapersDocument.DocumentLoadFlags) – flags from PapersDocument.DocumentLoadFlags

Raises:

GLib.Error

Returns:

True on success, or False on failure.

Return type:

bool

Loads self from uri.

On failure, False is returned and error is filled in. If the document is encrypted, PPS_DEFINE_ERROR_ENCRYPTED is returned. If the backend cannot load the specific document, PapersDocument.DocumentError.INVALID is returned. Other errors are possible too, depending on the backend used to load the document and the URI, e.g. GLib.IOError, GLib.FileError, and GLib.ConvertError.

render(rc)¶

Parameters:: rc (PapersDocument.RenderContext) –
Return type:: cairo.Surface

save(uri)¶

Parameters:: uri (str) – the target URI
Raises:: GLib.Error
Returns:: True on success, or False on error with error filled in
Return type:: bool

Saves self to uri.

set_modified(modified)¶

Parameters:: modified (bool) – a boolean value to set the document as modified or not.

Set the self modification state as modified.

New in version 3.28.

do_get_backend_info(info) virtual¶

Parameters:: info (PapersDocument.DocumentBackendInfo) –
Return type:: bool

do_get_info() virtual¶

Returns:: a PapersDocument.DocumentInfo
Return type:: PapersDocument.DocumentInfo

Returns the PapersDocument.DocumentInfo for the document.

do_get_n_pages() virtual¶

Return type:: int

do_get_page(index) virtual¶

Parameters:: index (int) – index of page
Returns:: Newly created PapersDocument.Page for the given index.
Return type:: PapersDocument.Page

do_get_page_label(page) virtual¶

Parameters:: page (PapersDocument.Page) –
Return type:: str

do_get_page_size(page_index) virtual¶

Parameters:

page_index (PapersDocument.Page) – index of page

Returns:

width:: return location for the width of the page, or None
height:: return location for the height of the page, or None

Return type:

(width: float, height: float)

do_get_thumbnail(rc) virtual¶

Parameters:: rc (PapersDocument.RenderContext) – an PapersDocument.RenderContext
Returns:: a GdkPixbuf.Pixbuf
Return type:: GdkPixbuf.Pixbuf

do_get_thumbnail_surface(rc) virtual¶

Parameters:: rc (PapersDocument.RenderContext) – an PapersDocument.RenderContext
Returns:: a cairo.Surface
Return type:: cairo.Surface

New in version 3.14.

do_load(uri) virtual¶

Parameters:: uri (str) – the document’s URI
Returns:: True on success, or False on failure.
Return type:: bool

Loads document from uri.

On failure, False is returned and error is filled in. If the document is encrypted, PPS_DEFINE_ERROR_ENCRYPTED is returned. If the backend cannot load the specific document, PapersDocument.DocumentError.INVALID is returned. If the backend does not support the format for the document’s contents, PapersDocument.DocumentError.UNSUPPORTED_CONTENT is returned. Other errors are possible too, depending on the backend used to load the document and the URI, e.g. GLib.IOError, GLib.FileError, and GLib.ConvertError.

do_load_fd(fd, flags) virtual¶

Parameters:

fd (int) – a file descriptor
flags (PapersDocument.DocumentLoadFlags) – flags from PapersDocument.DocumentLoadFlags

Returns:

True if loading succeeded, or False on error with error filled in

Return type:

bool

Synchronously loads the document from fd, which must refer to a regular file.

Note that this function takes ownership of fd; you must not ever operate on it again. It will be closed automatically if the document is destroyed, or if this function returns None.

See PapersDocument.Document.load() for more information.

New in version 42.0.

do_load_gfile(file, flags, cancellable) virtual¶

Parameters: