class Document(Model, MessageHandler)

A Document represents an application data structure that can be stored in a file. It implements standard functionality such as asking the user for file names and opening and closing files.

Each Document can have one or more windows associated with it. When the last window belonging to a document is closed, the document itself is closed.

A Document provides support for keeping track of whether it has been edited, and asking the user whether to save changes when it is closed.

Properties

needs_saving

A boolean indicating that the document has been edited and needs to be saved.

file

A FileRef identifying the file that the document was read from or last written to, or None.

file_type

A FileType specifying the type of file read and written by the document. This may be None if the document does not deal with files or does not care about file types.

title

Document title to be displayed in window headers. The default value of this property is derived from the last pathname component of the associated file, or if the document is not associated with a file, a title such as "Untitled-n" is constructed. Assigning to this property will cause all associated windows to update their titles accordingly.  

windows

Read-only. List of windows associated with this document.

page_setup

A PageSetup instance to be used by views having this document attached as a model.

Attributes

binary

Determines the mode in which the file object passed to the read_contents and write_contents methods is opened. If true, the file is opened in binary mode for reading or writing. If false, the file is opened in text mode for writing, and universal newlines mode for reading.

This attribute may be specified as a class attribute. The default value is true.

pickle_as_parent_model

(Read only) This is set to False as a class attribute, and you should not override it. Its purpose is to prevent the Document from being pickled along with a Model, as described here.

Abstract Methods

new_contents()

Should initialise the document to the appropriate state following a New command.

write_contents(file)

Should write the document's contents to the given file, which is an already-open file object.

read_contents(file)

Should initialise the document's contents by reading it from the given file, which is an already-open file object.

If you restore the contents by unpickling a previously-pickled Model whose parent attribute referred to the Document, you will need to re-set the parent here.

destroy_contents()

Called when the contents of the document are about to be discarded. If the contents contains any Model objects, they should be destroyed.

get_default_save_directory()

Called when the user is about to be asked for a location in which to save a document that has not been saved before, to find a defaultdirectory for request_new_file(). Should return a DirRef or FileRef, or None if there is no particular preferred location. The default implementation returns None.

get_default_save_filename()

Called when the user is about to be asked for a location in which to save a document that has not been saved before, to find a default file name for request_new_file(). Should return a suggested file name, or an empty string to require the user to enter a file name. The default implementation returns an empty string.

Methods

changed()

Mark the document as needing to be saved. Equivalent to setting the needs_saving property to true.

save_changes()

If the document has been edited, ask the user whether to save changes and do so if requested.

save_cmd()

Implements the standard Save command. Writes the document to its associated file, asking the user for one first if necessary.

save_as_cmd()

Implements the standard Save As... command. Asks the user for a new file and writes the document to it.

revert_cmd()

Implements the standard Revert command. Discards the current contents of the document and re-reads it from the associated file.

close_cmd()

Implements the standard Close command. Asks whether to save any changes, then destroys any associated windows.

page_setup_cmd()

Default implementation of the Page Setup... command. Edits the PageSetup instance referred to by the page_setup attribute. If it is None, a new PageSetup instance is created.

Destructor

destroy()

Destroys any associated Windows, then destroys the Document.

---