Commit 90a10736 authored by Jan Möbius's avatar Jan Möbius

BaseInterface documentation page finished

git-svn-id: http://www.openflipper.org/svnrepo/OpenFlipper/branches/Free@10995 383ad7c9-94d9-4d36-a494-682f7c89f535
parent 6ee5d264
......@@ -47,6 +47,7 @@
#include <QMenuBar>
#include <OpenFlipper/common/Types.hh>
/** \file BaseInterface.hh
*
* OpenFlippers main plugin Interface \ref baseInterfacePage.
......@@ -113,12 +114,13 @@ class BaseInterface {
*
* Emit this Signal, if you updated any part of an object.\n
* If you changed the element itself (geometry, topology,..) you also have to emit this signal.\n
* Dont emit this Signal in BaseInterface::slotObjectUpdated() as this causes an endless Loop!!
* Don't emit this Signal in BaseInterface::slotObjectUpdated() as this causes an endless Loop!!
* Give the id of the new object as parameter or -1 if you updated all objects or deleted an object.
* For performance reasons try to always give the id and not -1!
*
* The parameter has to be the id of the object or -1 if refering to all or deleted objects.
* @param _ objectId Id of the object or -1 if refering to all or deleted objects.
*/
virtual void updatedObject(int ) {};
virtual void updatedObject(int _objectId) {};
/** \brief An object has been changed or added by this plugin
*
......@@ -126,11 +128,12 @@ class BaseInterface {
* If you changed the element itself (geometry, topology,..) you also have to emit this signal.\n
* Dont emit this Signal in BaseInterface::slotObjectUpdated() as this causes an endless Loop!!
* Give the id of the new object as parameter or -1 if you updated all objects or deleted an object.
* For performance reasons try to always give the id and not -1!
*
* @param _identifier id of the object or -1 if refering to all or deleted objects.
* @param _type the type states which part of the object (topology, selection, ..) has to be updated
*/
virtual void updatedObject(int /*_identifier*/, const UpdateType /*_type*/) {};
virtual void updatedObject(int _identifier, const UpdateType _type) {};
/** \brief A scenegraph node has been shown or hidden
*
......@@ -139,7 +142,7 @@ class BaseInterface {
* an optimal view. Use the id of the object the node is attached to or -1 if it is not connected to an object.
*
*/
virtual void nodeVisibilityChanged( int /*_identifier*/ ) {};
virtual void nodeVisibilityChanged( int _identifier ) {};
private slots:
......@@ -153,7 +156,7 @@ class BaseInterface {
* You dont need to call updateView as the core triggers a redraw itself.
* @param _identifier Identifier of the updated/new object or -1 if one is deleted.
*/
virtual void slotObjectUpdated( int /*_identifier*/ ) {};
virtual void slotObjectUpdated( int _identifier ) {};
/** \brief An object has been updated by another plugin
*
......@@ -166,7 +169,7 @@ class BaseInterface {
* @param _identifier Identifier of the updated/new object or -1 if one is deleted.
* @param _type the type states which part of the object (topology, selection, ..) had been updated
*/
virtual void slotObjectUpdated( int /*_identifier*/, const UpdateType /*_type*/ ) {};
virtual void slotObjectUpdated( int _identifier, const UpdateType _type ) {};
/** \brief Called if the whole scene is cleared
*
......@@ -183,7 +186,7 @@ class BaseInterface {
* Addisionally you get the id of the object that has been changed or -1 if all objects
* have been modified.
*/
virtual void slotObjectSelectionChanged( int /*_identifier*/ ) {};
virtual void slotObjectSelectionChanged( int _identifier ) {};
/** \brief An object has been shown or hidden
*
......@@ -192,7 +195,7 @@ class BaseInterface {
* If multiple or all objects have changed, the id will be -1.
*
*/
virtual void slotVisibilityChanged( int /*_identifier*/ ) {};
virtual void slotVisibilityChanged( int _identifier ) {};
/** \brief Object properties have been changed
*
......@@ -201,7 +204,7 @@ class BaseInterface {
* If multiple or all objects have changed, the id will be -1.
*
*/
virtual void slotObjectPropertiesChanged( int /*_identifier*/ ) {};
virtual void slotObjectPropertiesChanged( int _identifier ) {};
/** \brief View has changed
*
......@@ -252,8 +255,8 @@ class BaseInterface {
* @param _parameters list of parameters
* @param _descriptions list of descriptions for the parameters (_descriptions[i] corresponds to _parameters[i])
*/
virtual void setSlotDescription(QString /*_slotName*/, QString /*_slotDescription*/,
QStringList /*_parameters*/, QStringList /*_descriptions*/) {};
virtual void setSlotDescription(QString _slotName , QString _slotDescription,
QStringList _parameters , QStringList _descriptions) {};
/** @} */
......@@ -310,20 +313,58 @@ this change. This functionality is provided by the signals and slots for \ref Ba
\image html updateObject.jpg
If you change data you have to emit one of BaseInterface::updatedObject(int) or BaseInterface::updatedObject(int,const UpdateType).
\n
BaseInterface::updatedObject(int) forces an update of the whole object while BaseInterface::updatedObject(int,const UpdateType)
can be restricted to a part of the object ( Geometry,Selection, ... ; see UpdateType ) and is therefore faster and should be preferred.
Both signals get the id of the object that has been updated.
Both signals get the id of the object that has been updated or -1 if all should be updated( you should not use -1 if you know what object changed!).
If the signal is emitted, the core calls BaseInterface::slotObjectUpdated( int , const UpdateType ) of every plugin. You can
implement this slot if you need to react on object changes.
After all plugins have been informed, the scene will be redrawn.
For more details about the UpdateType read the documentation about UpdateType and \ref DefaultUpdateTypes "predefined update types".
A description for adding custom update types at runtime is available \ref UpdateTypeFunctions "here".
It is also possible to insert custom nodes into the scenegraph. If you changed these nodes, you also have to inform the core.
This is achieved by the BaseInterface::nodeVisibilityChanged() function. As nodes they are usually attached to objects in the scene,
you should pass the id of the object to the function or -1 if its a global node (which should not be used!).
If the complete scene gets cleared, the slot BaseInterface::slotAllCleared() will be executed after all objects have been removed from the scene.
There are three additional slots that are called by the core, if the object selection(source/target BaseInterface::slotObjectSelectionChanged() ),
the object visibility(Show/Hide BaseInterface::slotVisibilityChanged()) or other properties changed (e.g. name BaseInterface::slotObjectPropertiesChanged() )
Remarks:
<ul>
<li>If the object id passed to the functions is -1 all objects should be treated as updated.
<li>Never emit the signal BaseInterface::updatedObject() inside the updated object slots as this causes endless loops!
</ul>
\section Scene Update Notifications
OpenFlipper manages the scene updates in its core. If objects get updated the scene will be automatically redrawn. Nevertheless,
you can force an update of the scene by emitting the signal BaseInterface::updateView().
If the view (viewer pos /viewing direction) has been changed, the slot BaseInterface::slotViewChanged() will be called. Be carefull, not to
change the view in this function or you get an endless loop!
\section Management Functions
There are some basic functions for managing plugins. The BaseInterface::description() function can be used
to provide a description for the plugin wich will be printed along with the plugin name. The BaseInterface::name()
function has to return the name of the plugin. This name will also be used inside the scripting system.
Additionally it is possible to provide a plugin version number with BaseInterface::version().
OpenFlippers scripting system can use all public slots defined in your plugin. If it should also provide a
small text description for your functions, you could set them with BaseInterface::setSlotDescription(). Even if
you do not implement scripting functions in your plugin, the core will then be able to provide this information
to the user.
Along with the scripting, OpenFlipper provides a batch mode, running without any user interface. If your plugin
will work without an user interface (e.g. only scripting functions), you can define a slot BaseInterface::noguiSupported().
This empty slot is used to tell the core, that the plugin can work in batch mode. Otherwise it will not be loaded
when running a batch file.
*/
......
......@@ -103,7 +103,6 @@ bool UpdateType::contains( const UpdateType& _type ) const {
// Catch the specialization of updates
if ( _type == UPDATE_SELECTION ) {
// if ( type_ == UPDATE_SELECTION_VERTICES.type_ || type_ == UPDATE_SELECTION_EDGES.type_ || type_ == UPDATE_SELECTION_FACES.type_ )
if ( type_ == UPDATE_SELECTION_VERTICES.type_ || type_ == UPDATE_SELECTION_EDGES.type_ || type_ == UPDATE_SELECTION_HALFEDGES.type_ || type_ == UPDATE_SELECTION_FACES.type_ || type_ == UPDATE_SELECTION_KNOTS.type_ )
return true;
}
......
......@@ -49,7 +49,16 @@
typedef std::bitset<64> UpdateTypeSet;
// TYPE
/** \brief Update type class
*
*
* This class is used to specify the scope of updates. There are update types for
* selection,geometry,topology,colors,... specified here: \ref DefaultUpdateTypes
*
* You can also find functions to add custom update types at runtime at
* \ref UpdateTypeFunctions
*
*/
class DLLEXPORT UpdateType {
public:
UpdateType(const UpdateType& _type);
......@@ -74,6 +83,12 @@ class DLLEXPORT UpdateType {
UpdateTypeSet type_;
};
/** \defgroup DefaultUpdateTypes Default update types
* The following update types are predefined for the general use cases
* @{
*
*/
/// Identifier for all updates
const UpdateType UPDATE_ALL( UpdateTypeSet(1) );
......@@ -81,8 +96,6 @@ const UpdateType UPDATE_ALL( UpdateTypeSet(1) );
const UpdateType UPDATE_VISIBILITY( UpdateTypeSet(1) << 1 );
/// The following update types are predefined for the general use cases
/** \brief Geometry updated
*
* Updated Geometry ( This update type has to be used if you only modify vertex positions of
......@@ -119,7 +132,7 @@ const UpdateType UPDATE_SELECTION_VERTICES( UpdateTypeSet(1) << 5 );
const UpdateType UPDATE_SELECTION_EDGES( UpdateTypeSet(1) << 6 );
/** \brief Edge selection has changed
/** \brief Halfedge selection has changed
*
* This is a more fine grained selection update. UPDATE_SELECTION will also match this update type.
*/
......@@ -146,10 +159,19 @@ const UpdateType UPDATE_COLOR( UpdateTypeSet(1) << 10 );
/// marks the last used ID
const UpdateType UPDATE_UNUSED ( UpdateTypeSet(1) << 11 );
/**@}*/
//=====================================================================================
// FUNCTIONS
//=====================================================================================
/** \defgroup UpdateTypeFunctions Runtime Update Types
* Use these functions to add custom update types at runtime.
* @{
*
*/
/** Adds a datatype and returns the id for the new type
*
* @param _name Internal name for the new DataType
......@@ -178,5 +200,6 @@ QString updateTypeName(UpdateType _id);
DLLEXPORT
uint updateTypeCount();
/**@}*/
#endif // UPDATETYPE_HH
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment