The `document` module¶

This module provides functions for working with documents. Most of the module-level functions are used for creating instances of the Document object.

document.find_by_filename(filename)¶

Finds a document with the given filename from the open documents.

Parameters:	filename – Filename of `Document` to find.
Returns:	A `Document` instance for the found document or `None`.

document.get_current()¶

Gets the currently active document.

Returns:	A `Document` instance for the currently active document or `None` if no documents are open.

document.get_from_page(page_num)¶

Gets a document based on it’s gtk.Notebook page number.

Parameters:	page_num – The tab number of the document in the documents notebook.
Returns:	A `Document` instance for the corresponding document or `None` if no document matched.

document.index(index)¶

Gets a document based on its index in Geany’s documents array.

Parameters:	index – The index of the document in Geany’s documents array.
Returns:	A `Document` instance for the corresponding document or `None` if not document matched, or the document that matched isn’t valid.

document.new_file([filename=None[, filetype=None[, text=None]]])¶

Creates a document file.

Parameters:	filename – The documents filename, or `None` for untitled. filetype – The documents filetype or `None` to auto-detect it from filename (if it’s not `None`) text – Initial text to put in the new document or `None` to leave it blank
Returns:	A `Document` instance for the new document.

document.open_file(filename[, read_only=False[, filetype=None[, forced_enc=None]]])¶

Open an existing document file.

Parameters:	filename – Filename of the document to open. read_only – Whether to open the document in read-only mode. filetype – Filetype to open the document as or `None` to detect it automatically. forced_enc – The file encoding to use or `None` to auto-detect it.
Returns:	A `Document` instance for the opened document or `None` if it couldn’t be opened.

document.open_files(filenames, read_only=False, filetype="", forced_enc="")¶

Open multiple files. This actually calls open_file() once for each filename in filenames.

Parameters:	filenames – List of filenames to open. read_only – Whether to open the document in read-only mode. filetype – Filetype to open the document as or `None` to detect it automatically. forced_enc – The file encoding to use or `None` to auto-detect it.

document.remove_page(page_num)¶

Remove a document from the documents array based on it’s page number in the documents notebook.

Parameters:	page_num – The tab number of the document in the documents notebook.
Returns:	`True` if the document was actually removed or `False` otherwise.

document.get_documents_list()¶

Get a list of open documents.

Returns:	A list of `Document` instances, one for each open document.

`Document` Objects¶

class document.Document¶

The main class holding information about a specific document. Unless otherwise noted, the attributes are read-only properties.

basename_for_display¶: The last part of the filename for this document, possibly truncated to a maximum length in case the filename is very long.

notebook_page¶: The page number in the gtk.Notebook containing documents.

status_color¶: Gets the status color of the document, or None if the default widget coloring should be used. The color is red if the document has changes, green if it’s read-only or None if the document is unmodified but writable. The value is a tuple of the RGB values for red, green, and blue respectively.

encoding¶: The encoding of this document. Must be a valid string representation of an encoding. This property is read-write.

file_type¶: The file type of this document as a Filetype instance. This property is read-write.

text_changed¶: Whether this document’s text has been changed since it was last saved.

file_name¶: The file name of this document.

has_bom¶: Indicates whether the document’s file has a byte-order-mark.

has_tags¶: Indicates whether this document supports source code symbols (tags) to show in the sidebar.

index¶: Index of the document in Geany’s documents array.

is_valid¶: Indicates whether this document is active and all properties are set correctly.

read_only¶: Whether the document is in read-only mode.

real_path¶: The link-dereferenced, locale-encoded file name for this document.

editor¶: The Editor instance associated with this document.

close()¶

Close this document.

Returns:	`True` if the document was closed, `False` otherwise.

reload([forced_enc=None])¶

Reloads this document.

Parameters:	forced_enc – The encoding to use when reloading this document or `None` to auto-detect it.
Returns:	`True` if the document was actually reloaded or `False` otherwise.

rename(new_filename)¶

Rename this document to a new file name. Only the file on disk is actually renamed, you still have to call save_as() to change the document object. It also stops monitoring for file changes to prevent receiving too many file change events while renaming. File monitoring is setup again in save_as().

Parameters:	new_filename – The new filename to rename to.

save([force=False])¶

Saves this documents file on disk.

Saving may include replacing tabs by spaces, stripping trailing spaces and adding a final new line at the end of the file, depending on user preferences. Then, the document-before-save signal is emitted, allowing plugins to modify the document before it’s saved, and the data is actually written to disk. The file type is set again or auto-detected if it wasn’t set yet. Afterwards, the document-save signal is emitted for plugins. If the file is not modified, this method does nothing unless force is set to True.

Note: You should ensure that file_name is not None before calling this; otherwise call dialogs.show_save_as().

Parameters:	force – Whether to save the document even if it’s not modified.
Returns:	`True` if the file was saved or `False` if the file could not or should not be saved.

save_as(new_filename)¶

Saves the document with a new filename, detecting the filetype.

Parameters:	new_filename – The new filename.
Returns:	`True` if the file was saved or `False` if it could not be saved.

The document module¶

Document Objects¶

The `document` module¶

`Document` Objects¶