Changeset db6b872 for molecuilder/src/Patterns/Observer.hpp

Timestamp:

Mar 4, 2010, 10:34:52 AM (16 years ago)

Author:

Tillmann Crueger <crueger@…>

Children:

fe3540

Parents:

d50264 (diff), f058ef (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.

Message:

Merge branch 'StructureRefactoring' into MenuRefactoring

File:

• molecuilder/src/Patterns/Observer.hpp (modified) (4 diffs)

molecuilder/src/Patterns/Observer.hpp

@@ -30 +30 @@
 class Observable;
 
+/**
+ * An Observer is notified by all Observed objects, when anything changes.
+ *
+ * If a simple change is done to an Object the Obervable will call the update() method
+ * of all signed on observers, passing itself as a parameter for identification. The
+ * Observers should then react to the changes and update themselves accordingly.
+ *
+ * If an observed Object is destroyed it will call the subjectKilled() method
+ * of all signed on Observers, again passing itself as a parameter for identification.
+ * The Observers should handle the destruction of an observed Object gracefully, i.e.
+ * set themselves inactive, display something else, etc. There is no need
+ * to sign of from the dying object, since this will be handled by the Observable destructor.
+ */
 class Observer
 {
@@ -38 +51 @@
 
 protected:
+  /**
+   * This method is called upon changes of the Observable
+   */
   virtual void update(Observable *publisher)=0;
+
+  /**
+   * This method is called when the observed object is destroyed.
+   */
   virtual void subjectKilled(Observable *publisher)=0;
 };
 
+/**
+ * An Observable implements all neccessary method for being observed.
+ *
+ * That is, it provides methods for signing on and of from an
+ * Observable that can be used by any observer. The actual
+ * observer-mechanism is handled at a central static place
+ * to avoid memory issues when many observable are around but only few
+ * are actually observed.
+ */
 class Observable : public Observer {
 public:
@@ -47 +76 @@
   virtual ~Observable();
 
+  /**
+   * Sign an Observer on to this Observable. The Observer will be notified
+   * whenever something inside the Observable changes. The Observer can
+   * assign itself a priority for the changes in the range of -20:+20.
+   * The Observer with lower priority will be called before the others,
+   * same as with Unix nice-levels. This can be used when an Object
+   * contains other objects that observe it (derived values), and these objects have
+   * to recalculate their states before the changes should be propageted to the
+   * UI. A default priority of 0 should be fine in most cases, since there is
+   * ussually no need to order the update sequence.
+   */
   virtual void signOn(Observer *target, int priority=0);
+
+  /**
+   * Sign of a previously signed on Observer. After this no more
+   * updates will be recieved from that observer.
+   */
   virtual void signOff(Observer *target);
 
@@ -76 +121 @@
   // Structure for RAII-Style notification
 protected:
+  /**
+   * This structure implements the Observer-mechanism RAII-Idiom.
+   * It triggers certain functions on creation and destruction so that
+   * Observer mechanisms can be linked to scope block.
+   */
   class _Observable_protector {
   public: