zim.notebook.page.Page

class documentation

class Page(Path, SignalEmitter): (source)

Class to represent a single page in the notebook.

Page objects inherit from Path but have internal state reflecting content in the notebook. We try to keep Page objects unique by hashing them in Notebook.get_page(), Path object on the other hand are cheap and can have multiple instances for the same logical path. We ask for a path object instead of a name in the constructor to encourage the use of Path objects over passing around page names as string.

You can use a Page object instead of a Path anywhere in the APIs where a path is needed as argument etc.

Unknown Field: signal
`storage-changed (changed-on-disk)`: signal emitted on page change. The argument "changed-on-disk" is `True` when an external edit was detected. For internal edits it is `False`.
`modified-changed ()`: emitted when the page is edited

Method	`__init__`	Constructor.
Method	`append_parsetree`	Append content
Method	`check_source_changed`	Checks for changes in the source file and load it if needed
Method	`dump`	Get content in a specific format
Method	`exists`	`True` when the page has either content or children
Method	`get_anchors`	Generator returning all the (explicit) anchors in the page content
Method	`get_links`	Generator for links in the page content
Method	`get_parsetree`	Returns the contents of the page
Method	`get_tags`	Generator for tags in the page content
Method	`get_textbuffer`	Get a `Gtk.TextBuffer` for the page
Method	`get_title`	Undocumented
Method	`heading_matches_pagename`	No summary
Method	`isequal`	No summary
Method	`on_buffer_modified_changed`	Undocumented
Method	`parse`	Store formatted text in the page
Method	`reload_textbuffer`	Reload page content from source file and update the textbuffer if set
Method	`set_modified`	Undocumented
Method	`set_parsetree`	Set the parsetree with content for this page
Class Variable	`__signals__`	Undocumented
Instance Variable	`attachments_folder`	Undocumented
Instance Variable	`format`	Undocumented
Instance Variable	`haschildren`	`True` if the page has sub-pages
Instance Variable	`name`	full page name (inherited from `Path`)
Instance Variable	`source_file`	Undocumented
Property	`ctime`	Undocumented
Property	`hascontent`	Returns whether this page has content
Property	`modified`	Undocumented
Property	`mtime`	Undocumented
Property	`readonly`	Undocumented
Method	`_set_parsetree`	Undocumented
Method	`_store`	Undocumented
Method	`_store_tree`	Undocumented
Instance Variable	`_change_counter`	Undocumented
Instance Variable	`_last_etag`	Undocumented
Instance Variable	`_meta`	Undocumented
Instance Variable	`_modified`	Undocumented
Instance Variable	`_parsetree`	Undocumented
Instance Variable	`_readonly`	Undocumented
Instance Variable	`_textbuffer`	Undocumented

Inherited from Path:

Class Method	`new_from_zim_config`	Returns a new object based on the string representation for that path.
Static Method	`assertValidPageName`	No summary
Static Method	`makeValidPageName`	No summary
Method	`__add__`	`path + name` is an alias for `path.child(name)`
Method	`__eq__`	Paths are equal when their names are the same
Method	`__hash__`	Undocumented
Method	`__ne__`	Paths are not equal when their names are not the same
Method	`__repr__`	Undocumented
Method	`__str__`	Undocumented
Method	`child`	Get a child Path
Method	`commonparent`	Find a common parent for two Paths
Method	`ischild`	Check whether this path is a child of a given path @param parent: a `Path` object @returns: True when this path is a (grand-)child of `parent`
Method	`match_namespace`	Check whether this path is in a specific section of the notebook @param namespace: a `Path` object @returns: True when this path is equal to `namespace` or is a (grand-)child of `namespace`
Method	`parents`	Generator function for parent Paths including root
Method	`relname`	Get a part of this path relative to a parent path
Method	`serialize_zim_config`	Returns the name for serializing this path
Class Variable	`__slots__`	Undocumented
Property	`basename`	Get the basename of the path (last part of the name)
Property	`isroot`	`True` when this Path represents the top level namespace
Property	`namespace`	Gives the name for the parent page. Returns an empty string for the top level namespace.
Property	`parent`	Get the path for the parent page
Property	`parts`	Get all the parts of the name (split on ":")

Inherited from SignalEmitter:

Method	`__new__`	Undocumented
Method	`block_signals`	Returns a context manager for blocking one or more signals
Method	`connect`	Register a handler for a specific object.
Method	`connect_after`	Like `connect()` but handler will be called after default handler
Method	`disconnect`	Undocumented
Method	`emit`	Undocumented
Method	`emit_return_first`	Emits a signal and stops emission on the first handler that returns a not-None value.
Method	`emit_return_iter`	Returns an generator that calls one handler on each iteration and yields the return values. This allows aggregating return values.
Method	`_connect`	Undocumented
Method	`_setup_signal`	Undocumented
Method	`_teardown_signal`	Undocumented

def __init__(self, path, haschildren, file, folder, format): (source)

overrides zim.notebook.page.Path.__init__

Constructor.

Parameters
path	Undocumented
haschildren	Undocumented
file	Undocumented
folder	Undocumented
format	Undocumented
name	the absolute page name in the right case as a string or as a tuple strings The name ":" is used as a special case to construct a path for the toplevel namespace in a notebook.
Note
This constructor does not do any checks for the sanity of the path name. Never construct a path directly from user input, but use either `index.lookup_from_user_input()` or first check the name with `makeValidPageName()`

def append_parsetree(self, tree): (source)

Append content

Parameters
tree	a `zim.formats.ParseTree` object with content

def check_source_changed(self): (source)

Checks for changes in the source file and load it if needed

If the page has a textbuffer and it contains unsaved changes, this method will not overwrite them and you'll get an error on next attempt to save. To force overwrite see reload_textbuffer()

def dump(self, format, linker=None): (source)

Get content in a specific format

Convenience method that converts the current parse tree to a particular format first.

Parameters
format	either a format module or a string that is understood by `zim.formats.get_format()`.
linker	a linker object (see e.g. `BaseLinker`)
Returns
text as a list of lines or an empty list

def exists(self): (source)

True when the page has either content or children

def get_anchors(self): (source)

Generator returning all the (explicit) anchors in the page content

def get_links(self): (source)

Generator for links in the page content

This method gives the raw links from the content, if you want nice Link objects use index.list_links() instead.

Returns

yields a list of 3-tuples (type, href, attrib) where:

type is the link type (e.g. "page" or "file")
href is the link itself
attrib is a dict with link properties

def get_parsetree(self): (source)

Returns the contents of the page

Returns
a `zim.formats.ParseTree` object or `None`

def get_tags(self): (source)

Generator for tags in the page content

Returns
yields an unordered list of unique 2-tuples `(name, attrib)` for tags in the parsetree.

def get_textbuffer(self, constructor=None): (source)

Get a Gtk.TextBuffer for the page

Will either return an existing buffer or construct a new one and return it. A Gtk.TextBuffer can be shared between multiple Gtk.TextViews. The page object owns the textbuffer to allow multiple views on the same page.

Once a buffer is set, also methods like get_parsetree() and get_parsetree() will interact with this buffer.

Parameters
constructor	if not buffer was set previously, this function is called to construct the buffer.
Returns
a `TextBuffer` object or `None` if no buffer is set and no constructor is provided.

def get_title(self): (source)

Undocumented

def heading_matches_pagename(self): (source)

Returns whether the heading matches the page name. Used to determine whether the page should have its heading auto-changed on rename/move.

Returns
`True` when the heading can be auto-changed.

def isequal(self, other): (source)

Check equality of pages This method is intended to deal with case-insensitive storage backends (e.g. case insensitive file system) where the method is supposed to check equality of the resource. Note that this may be the case even when the page objects differ and can have a different name (so __cmp__ will not show them to be equal). However default falls back to __cmp__.

Returns
`True` of both page objects point to the same resource
Unknown Field: implementation
can be implementated by subclasses

def on_buffer_modified_changed(self, buffer): (source)

Undocumented

def parse(self, format, text, append=False): (source)

Store formatted text in the page

Convenience method that parses text and sets the parse tree accordingly.

Parameters
format	either a format module or a string that is understood by `zim.formats.get_format()`.
text	text as a string or as a list of lines
append	if `True` the text is appended instead of replacing current content.

def reload_textbuffer(self): (source)

Reload page content from source file and update the textbuffer if set

NOTE: this method overwrites any changes in the textbuffer or parsetree that have not been saved to file !

def set_modified(self, modified): (source)

Undocumented

def set_parsetree(self, tree): (source)

Set the parsetree with content for this page

Parameters
tree	a `zim.formats.ParseTree` object with content or `None` to remove all content from the page
Note
after setting new content in the Page object it still needs to be stored in the notebook to save this content permanently. See `Notebook.store_page()`.