A Model represents an application data structure which can have observers.
The observers are typically subclasses of View, but need not be. Class Model
provides mechanisms for attaching and removing observers, and for notifying
observers when the Model changes.
A Model can have another Model or Document as a parent. When you call the changed()
method of a Model, the call is propagated to its parent, if any. If the
Model is ultimately contained in a Document, that Document will then be
marked as needing to be saved.
are designed to be pickled as a convenient way of saving and restoring
the state of a Document. There are two ways in which class Model
provides special support for pickling.
- The link
between a Model and its observers is maintained outside the Model
object, so that the observers will not be pickled along with the Model.
is a mechanism to prevent the parent object of a Model from being
pickled when it would not be appropriate to do so. By default, this
mechanism is used to prevent a Document reached via the parent
attribute of a Model from being pickled. This is important, because
normally you only want to save the contents of a Document, not the
Document object itself. Furthermore, the Document contains references
to the Application and all of the Windows attached to it, so pickling
the Document would result in attempting to pickle almost the entire
state of the application.
The mechanism involves looking for an attribute called pickle_as_parent_model on the object referenced by the model's parent attribute. If that attribute exists and has a false value, then the parent attribute is omitted from the pickled state of the Model. Class Document has a pickle_as_parent_model attribute that defaults to False (and you should not change it).
consequence is that the parent link from a Model to a containing
Document is not automatically restored. You will need to set it
yourself after unpickling in the Document's read_contents() method.
- Model(parent = None)
- Creates a Model with the specified parent.
- List of objects which are observing this Model. Do not modify this
list directly; use the add_view and remove_view methods
to add and remove observers.
- Containing Model or Document, if any.
- Adds the given object as an observer of this Model. If the object
defines an add_model method, it is called with this Model as argument.
- Removes the given object as an observer of this Model. If the object
defines a remove_model method, it is called with this Model as argument.
- notify_views(message = 'model_changed', ...)
- Calls a method of each observer with the same name as the message,
passing it any additional arguments.
- If the Model is contained in a Document, mark the Document as needing to be saved.
- These methods implement the special treatment of the parent attribute when pickling. The __getstate__ method returns a possibly-modified version of the Model's __dict__, and the __setstate__ method restores it. If you implement your own custom pickling behaviour, you should build on these methods.
- Dissociates the Model from any attached observers, and calls the
model_destroyed method of each observer which defines it.