Changeset dbb474 for src/Patterns/Observer.hpp

Timestamp:

Mar 3, 2010, 1:57:41 PM (15 years ago)

Author:

Tillmann Crueger <crueger@…>

Branches:

Action_Thermostats, Add_AtomRandomPerturbation, Add_FitFragmentPartialChargesAction, Add_RotateAroundBondAction, Add_SelectAtomByNameAction, Added_ParseSaveFragmentResults, AddingActions_SaveParseParticleParameters, Adding_Graph_to_ChangeBondActions, Adding_MD_integration_tests, Adding_ParticleName_to_Atom, Adding_StructOpt_integration_tests, AtomFragments, Automaking_mpqc_open, AutomationFragmentation_failures, Candidate_v1.5.4, Candidate_v1.6.0, Candidate_v1.6.1, ChangeBugEmailaddress, ChangingTestPorts, ChemicalSpaceEvaluator, CombiningParticlePotentialParsing, Combining_Subpackages, Debian_Package_split, Debian_package_split_molecuildergui_only, Disabling_MemDebug, Docu_Python_wait, EmpiricalPotential_contain_HomologyGraph, EmpiricalPotential_contain_HomologyGraph_documentation, Enable_parallel_make_install, Enhance_userguide, Enhanced_StructuralOptimization, Enhanced_StructuralOptimization_continued, Example_ManyWaysToTranslateAtom, Exclude_Hydrogens_annealWithBondGraph, FitPartialCharges_GlobalError, Fix_BoundInBox_CenterInBox_MoleculeActions, Fix_ChargeSampling_PBC, Fix_ChronosMutex, Fix_FitPartialCharges, Fix_FitPotential_needs_atomicnumbers, Fix_ForceAnnealing, Fix_IndependentFragmentGrids, Fix_ParseParticles, Fix_ParseParticles_split_forward_backward_Actions, Fix_PopActions, Fix_QtFragmentList_sorted_selection, Fix_Restrictedkeyset_FragmentMolecule, Fix_StatusMsg, Fix_StepWorldTime_single_argument, Fix_Verbose_Codepatterns, Fix_fitting_potentials, Fixes, ForceAnnealing_goodresults, ForceAnnealing_oldresults, ForceAnnealing_tocheck, ForceAnnealing_with_BondGraph, ForceAnnealing_with_BondGraph_continued, ForceAnnealing_with_BondGraph_continued_betteresults, ForceAnnealing_with_BondGraph_contraction-expansion, FragmentAction_writes_AtomFragments, FragmentMolecule_checks_bonddegrees, GeometryObjects, Gui_Fixes, Gui_displays_atomic_force_velocity, ImplicitCharges, IndependentFragmentGrids, IndependentFragmentGrids_IndividualZeroInstances, IndependentFragmentGrids_IntegrationTest, IndependentFragmentGrids_Sole_NN_Calculation, JobMarket_RobustOnKillsSegFaults, JobMarket_StableWorkerPool, JobMarket_unresolvable_hostname_fix, MoreRobust_FragmentAutomation, ODR_violation_mpqc_open, PartialCharges_OrthogonalSummation, PdbParser_setsAtomName, PythonUI_with_named_parameters, QtGui_reactivate_TimeChanged_changes, Recreated_GuiChecks, Rewrite_FitPartialCharges, RotateToPrincipalAxisSystem_UndoRedo, SaturateAtoms_findBestMatching, SaturateAtoms_singleDegree, StoppableMakroAction, Subpackage_CodePatterns, Subpackage_JobMarket, Subpackage_LinearAlgebra, Subpackage_levmar, Subpackage_mpqc_open, Subpackage_vmg, Switchable_LogView, ThirdParty_MPQC_rebuilt_buildsystem, TrajectoryDependenant_MaxOrder, TremoloParser_IncreasedPrecision, TremoloParser_MultipleTimesteps, TremoloParser_setsAtomName, Ubuntu_1604_changes, stable

Children:

1c51c8

Parents:

a1510d

Message:

Improved Doxygen documentation

File:

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

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: