Merge branch 'ctkVTKObject-doxygen-doc'

* ctkVTKObject-doxygen-doc:
  Comment qvtk???Connect methods added by QVTK_OBJECT

Documentation/Doxyfile.txt.in

@@ -1559,7 +1559,7 @@ ENABLE_PREPROCESSING   = YES
 # compilation will be performed. Macro expansion can be done in a controlled
 # way by setting EXPAND_ONLY_PREDEF to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
 # then the macro expansion is limited to the macros specified with the
@@ -1608,7 +1608,7 @@ EXPAND_AS_DEFINED      =
 # that are alone on a line, have an all uppercase name, and do not end with a
 # semicolon, because these will confuse the parser if not removed.
 
-SKIP_FUNCTION_MACROS   = YES
+SKIP_FUNCTION_MACROS   = NO
 
 #---------------------------------------------------------------------------
 # Configuration::additions related to external references

Libs/Visualization/VTK/Core/ctkVTKObject.h

@@ -28,7 +28,14 @@
 /// @{
 
 //-----------------------------------------------------------------------------
+/// Define qvtkConnect()
+/// \sa qvtkConnect(), QVTK_OBJECT
 #define QVTK_OBJECT_ADD_CONNECTION_METHOD                               \
+/** \brief Connect a vtkObject event with a QObject slot.*/             \
+/** Utility function that calls addConnection() on ctkVTKObjectEventsObserver.*/\
+/** \sa ctkVTKObjectEventsObserver::addConnection(),*/                  \
+/** qvtkReconnect(), qvtkDisconnect(), qvtkDisconnectAll(),*/           \
+/** qvtkIsConnected(), QVTK_OBJECT_ADD_CONNECTION_METHOD*/              \
 QString qvtkConnect(vtkObject* vtk_obj, unsigned long vtk_event,        \
                     const QObject* qt_obj, const char* qt_slot,         \
                     float priority = 0.0,                               \
@@ -39,7 +46,18 @@ QString qvtkConnect(vtkObject* vtk_obj, unsigned long vtk_event,        \
 }
 
 //-----------------------------------------------------------------------------
+/// Define qvtkReconnect()
+/// \sa qvtkReconnect(), QVTK_OBJECT
 #define QVTK_OBJECT_RECONNECT_METHOD                                    \
+/** \brief Disconnect and reconnect a QObject slot with a new vtkObject event.*/ \
+/** Internally calls ctkVTKObjectEventsObserver::addConnection().*/     \
+/** The existing connection between \a old_vtk_obj and \a qt_obj*/      \
+/** for the event \a vtk_event and the slot \a qt_slot is disconnected.*/\
+/** And the \a vtk_obj is then connected using the same parameters.*/   \
+/** \sa ctkVTKObjectEventsObserver::addConnection(),*/                  \
+/** qvtkReconnect(vtkObject*,unsigned long,const QObject*,const char*,float,*/\
+/** Qt::ConnectionType), qvtkConnect(), qvtkDisconnect(), */            \
+/** qvtkIsConnected(), QVTK_OBJECT_RECONNECT_METHOD*/                   \
 QString qvtkReconnect(vtkObject* old_vtk_obj, vtkObject* vtk_obj,       \
                       unsigned long vtk_event, const QObject* qt_obj,   \
                       const char* qt_slot, float priority = 0.0,        \
@@ -50,7 +68,18 @@ QString qvtkReconnect(vtkObject* old_vtk_obj, vtkObject* vtk_obj,       \
 }
 
 //-----------------------------------------------------------------------------
+/// Define qvtkReconnect()
+/// \sa qvtkReconnect(), QVTK_OBJECT
 #define QVTK_OBJECT_RECONNECT_METHOD_2                                  \
+/** \brief Disconnect and reconnect a new vtkObject event with a QObject slot.*/\
+/** Utility function that calls reconnection() on ctkVTKObjectEventsObserver.*/\
+/** Any existing connection between a vtkObject and \a qt_obj*/         \
+/** for the event \a vtk_event and the slot \a qt_slot is disconnected.*/\
+/** And the \a vtk_obj is then connected using the same parameters.*/   \
+/** \sa ctkVTKObjectEventsObserver::reconnection(),*/                   \
+/** qvtkReconnect(vtkObject*,vtkObject*,unsigned long,const QObject*,*/ \
+/** const char*,float,Qt::ConnectionType), qvtkConnect(),*/             \
+/** qvtkDisconnect(), qvtkIsConnected(), QVTK_OBJECT_RECONNECT_METHOD_2*/\
 QString qvtkReconnect(vtkObject* vtk_obj,                               \
                       unsigned long vtk_event, const QObject* qt_obj,   \
                       const char* qt_slot, float priority = 0.0,        \
@@ -61,7 +90,20 @@ QString qvtkReconnect(vtkObject* vtk_obj,                               \
 }
 
 //-----------------------------------------------------------------------------
+/// Define qvtkDisconnect()
+/// \sa qvtkDisconnect(), QVTK_OBJECT
 #define QVTK_OBJECT_REMOVE_CONNECTION_METHOD                            \
+/** \brief Disconnect a vtkObject event with a QObject slot.*/          \
+/** Utility function that calls removeConnection() on*/                 \
+/** ctkVTKObjectEventsObserver.*/                                       \
+/** Remove any existing connection between \a vtk_obj and \a qt_obj that*/\
+/** match the \a vtk_event event and \a qt_slot slot.*/                 \
+/** 0 (or vtkCommand::NoEvent for \a vtk_event) for any parameter is considered*/\
+/** as a wildcard, it makes the parameter criteria to be ignored*/      \
+/** (matches all connections).*/                                        \
+/** \sa ctkVTKObjectEventsObserver::removeConnection(),*/               \
+/** qvtkConnect(), qvtkReconnect(), qvtkDisconnectAll(),*/              \
+/** qvtkIsConnected(), QVTK_OBJECT_REMOVE_CONNECTION_METHOD*/           \
 int qvtkDisconnect(vtkObject* vtk_obj, unsigned long vtk_event,         \
   const QObject* qt_obj, const char* qt_slot)                           \
 {                                                                       \
@@ -70,14 +112,30 @@ int qvtkDisconnect(vtkObject* vtk_obj, unsigned long vtk_event,         \
 }
 
 //-----------------------------------------------------------------------------
+/// Define qvtkDisconnectAll()
+/// \sa qvtkDisconnectAll(), QVTK_OBJECT
 #define QVTK_OBJECT_REMOVEALL_CONNECTION_METHOD                         \
+/** \brief Disconnect all created connections between vtkObjects and QObjects. */\
+/** Utility function that calls removeAllConnections() on */            \
+/** ctkVTKObjectEventsObserver. */                                      \
+/** \sa ctkVTKObjectEventsObserver::removeAllConnections(),*/           \
+/** qvtkConnect(), qvtkReconnect(), qvtkDisconnect() */                 \
+/** qvtkIsConnected(), QVTK_OBJECT_REMOVEALL_CONNECTION_METHOD */       \
 int qvtkDisconnectAll()                                                 \
 {                                                                       \
   return MyQVTK.removeAllConnections();                                 \
 }
 
 //-----------------------------------------------------------------------------
+/// Define qvtkIsConnected()
+/// \sa qvtkIsConnected(), QVTK_OBJECT
 #define QVTK_OBJECT_IS_CONNECTION_METHOD                                \
+/** \brief Check if a connection exists.*/                              \
+/** Utility function that calls and returns containsConnection() from*/ \
+/** ctkVTKObjectEventsObserver.*/                                       \
+/** \sa ctkVTKObjectEventsObserver::containsConnection(),*/             \
+/** qvtkConnect(), qvtkReconnect(), qvtkDisconnect()*/                  \
+/** qvtkDisconnectAll(), QVTK_OBJECT_IS_CONNECTION_METHOD*/             \
 bool qvtkIsConnected(vtkObject* vtk_obj = 0,                            \
                      unsigned long vtk_event = vtkCommand::NoEvent,     \
                      const QObject* qt_obj = 0,                         \
@@ -88,6 +146,9 @@ bool qvtkIsConnected(vtkObject* vtk_obj = 0,                            \
 }
 
 //-----------------------------------------------------------------------------
+/// Define qvtkBlock(vtkObject* vtk_obj, unsigned long vtk_event,
+/// const QObject* qt_obj)
+/// \sa qvtkBlock(), QVTK_OBJECT
 #define QVTK_OBJECT_BLOCK_CONNECTION_METHOD                              \
 void qvtkBlock(vtkObject* vtk_obj, unsigned long vtk_event,              \
   const QObject* qt_obj)                                                 \
@@ -96,6 +157,8 @@ void qvtkBlock(vtkObject* vtk_obj, unsigned long vtk_event,              \
 }
 
 //-----------------------------------------------------------------------------
+/// Define qvtkBlock(const QString& id, bool blocked)
+/// \sa qvtkBlock(const QString& id, bool blocked), QVTK_OBJECT
 #define QVTK_OBJECT_BLOCK_CONNECTION_METHOD2                             \
 void qvtkBlock(const QString& id, bool blocked)                          \
 {                                                                        \
@@ -103,6 +166,8 @@ void qvtkBlock(const QString& id, bool blocked)                          \
 }
 
 //-----------------------------------------------------------------------------
+/// Define qvtkBlockAll()
+/// \sa qvtkBlockAll(), QVTK_OBJECT
 #define QVTK_OBJECT_BLOCKALL_CONNECTION_METHOD                          \
 bool qvtkBlockAll()                                                     \
 {                                                                       \
@@ -110,6 +175,8 @@ bool qvtkBlockAll()                                                     \
 }
 
 //-----------------------------------------------------------------------------
+/// Define qvtkBlockAll()
+/// \sa qvtkBlockAll(), QVTK_OBJECT
 #define QVTK_OBJECT_BLOCKALL_CONNECTION_METHOD2                         \
 bool qvtkBlockAll(bool block)                                           \
 {                                                                       \
@@ -117,6 +184,8 @@ bool qvtkBlockAll(bool block)                                           \
 }
 
 //-----------------------------------------------------------------------------
+/// Define qvtkUnblock()
+/// \sa qvtkUnblock(), QVTK_OBJECT
 #define QVTK_OBJECT_UNBLOCK_CONNECTION_METHOD                           \
 void qvtkUnblock(vtkObject* vtk_obj, unsigned long vtk_event,           \
   const QObject* qt_obj)                                                \
@@ -125,6 +194,8 @@ void qvtkUnblock(vtkObject* vtk_obj, unsigned long vtk_event,           \
 }
 
 //-----------------------------------------------------------------------------
+/// Define qvtkUnblockAll()
+/// \sa qvtkUnblockAll(), QVTK_OBJECT
 #define QVTK_OBJECT_UNBLOCKALL_CONNECTION_METHOD                        \
 bool qvtkUnblockAll()                                                   \
 {                                                                       \
@@ -132,6 +203,22 @@ bool qvtkUnblockAll()                                                   \
 }
 
 //-----------------------------------------------------------------------------
+/// \brief Define VTK/Qt event/slot connection utility methods.
+/// It is a convenient macro that declares and defines utility methods for
+/// connecting vtkObjects with QObjects. It connects the vtkObject event
+/// mechanism with the QObject slot mechanism.
+/// Can be called in any QObject derived class declaration,typically after the
+/// Q_OBJECT macro.
+/// \sa ctkVTKObjectEventsObserver, qvtkConnect(),
+/// qvtkReconnect(),qvtkDisconnect(), qvtkDisconnectAll(), qvtkIsConnected(),
+/// QVTK_OBJECT_ADD_CONNECTION_METHOD, QVTK_OBJECT_RECONNECT_METHOD,
+/// QVTK_OBJECT_RECONNECT_METHOD_2, QVTK_OBJECT_REMOVE_CONNECTION_METHOD,
+/// QVTK_OBJECT_REMOVEALL_CONNECTION_METHOD, QVTK_OBJECT_IS_CONNECTION_METHOD,
+/// QVTK_OBJECT_BLOCK_CONNECTION_METHOD, QVTK_OBJECT_BLOCK_CONNECTION_METHOD2,
+/// QVTK_OBJECT_UNBLOCK_CONNECTION_METHOD,
+/// QVTK_OBJECT_BLOCKALL_CONNECTION_METHOD,
+/// QVTK_OBJECT_BLOCKALL_CONNECTION_METHOD2,
+/// QVTK_OBJECT_UNBLOCKALL_CONNECTION_METHOD
 #define QVTK_OBJECT                                \
 protected:                                         \
   QVTK_OBJECT_ADD_CONNECTION_METHOD                \

Libs/Visualization/VTK/Core/ctkVTKObjectEventsObserver.cpp

@@ -402,6 +402,12 @@ int ctkVTKObjectEventsObserver::removeConnection(vtkObject* vtk_obj, unsigned lo
 }
 
 //-----------------------------------------------------------------------------
+int ctkVTKObjectEventsObserver::removeAllConnections()
+{
+  return this->removeConnection(0, vtkCommand::NoEvent, 0, 0);
+}
+
+//-----------------------------------------------------------------------------
 bool ctkVTKObjectEventsObserver::containsConnection(vtkObject* vtk_obj, unsigned long vtk_event,
   const QObject* qt_obj, const char* qt_slot)const
 {

Libs/Visualization/VTK/Core/ctkVTKObjectEventsObserver.h

@@ -21,44 +21,20 @@
 #ifndef __ctkVTKObjectEventsObserver_h
 #define __ctkVTKObjectEventsObserver_h
 
-/// CTK includes
-#include <ctkSingleton.h>
-
 /// Qt includes
 #include <QObject>
 #include <QList>
 #include <QString>
 
-/// VTK includes
-#include <vtkCommand.h>
-
+/// CTK includes
+#include <ctkSingleton.h>
 #include "ctkVisualizationVTKCoreExport.h"
-
 class ctkVTKConnection;
-class vtkObject;
-class ctkVTKObjectEventsObserver;
 class ctkVTKObjectEventsObserverPrivate;
 
-//-----------------------------------------------------------------------------
-/// \ingroup Visualization_VTK_Core
-class CTK_VISUALIZATION_VTK_CORE_EXPORT ctkVTKConnectionFactory
-{
-public:
-  static ctkVTKConnectionFactory* instance();
-
-  /// The singleton takes ownerchip of the new factory instance and will take care
-  /// of cleaning the memory.
-  /// \note If \a newInstance is not null, the current factory instance will be
-  /// deleted. Note also that setting a null \a newInstance is a no-op.
-  static void setInstance(ctkVTKConnectionFactory* newInstance);
-
-  virtual ctkVTKConnection* createConnection(ctkVTKObjectEventsObserver*)const;
-protected:
-  ctkVTKConnectionFactory();
-  virtual ~ctkVTKConnectionFactory();
-  CTK_SINGLETON_DECLARE(ctkVTKConnectionFactory)
-};
-CTK_SINGLETON_DECLARE_INITIALIZER(CTK_VISUALIZATION_VTK_CORE_EXPORT, ctkVTKConnectionFactory)
+/// VTK includes
+#include <vtkCommand.h>
+class vtkObject;
 
 //-----------------------------------------------------------------------------
 /// \ingroup Visualization_VTK_Core
@@ -137,7 +113,7 @@ public:
 
   ///
   /// Remove all the connections
-  inline int removeAllConnections();
+  int removeAllConnections();
 
   ///
   /// Temporarilly block all the connection
@@ -158,8 +134,9 @@ public:
   /// Return true if the connection exists and was blocked, otherwise returns
   /// false.
   bool blockConnection(const QString& id, bool blocked);
-  
-  /// Return true if there is at least 1 connection that match the parameter
+
+  /// Return true if there is at least 1 connection matching the parameters,
+  /// false otherwise.
   bool containsConnection(vtkObject* vtk_obj, unsigned long vtk_event = vtkCommand::NoEvent,
                           const QObject* qt_obj =0, const char* qt_slot =0)const;
 
@@ -173,9 +150,24 @@ private:
 };
 
 //-----------------------------------------------------------------------------
-int ctkVTKObjectEventsObserver::removeAllConnections()
+/// \ingroup Visualization_VTK_Core
+class CTK_VISUALIZATION_VTK_CORE_EXPORT ctkVTKConnectionFactory
 {
-  return this->removeConnection(0, vtkCommand::NoEvent, 0, 0);
-}
+public:
+  static ctkVTKConnectionFactory* instance();
+
+  /// The singleton takes ownerchip of the new factory instance and will take care
+  /// of cleaning the memory.
+  /// \note If \a newInstance is not null, the current factory instance will be
+  /// deleted. Note also that setting a null \a newInstance is a no-op.
+  static void setInstance(ctkVTKConnectionFactory* newInstance);
+
+  virtual ctkVTKConnection* createConnection(ctkVTKObjectEventsObserver*)const;
+protected:
+  ctkVTKConnectionFactory();
+  virtual ~ctkVTKConnectionFactory();
+  CTK_SINGLETON_DECLARE(ctkVTKConnectionFactory)
+};
+CTK_SINGLETON_DECLARE_INITIALIZER(CTK_VISUALIZATION_VTK_CORE_EXPORT, ctkVTKConnectionFactory)
 
 #endif