Commit c31dbdfd authored by Jan Möbius's avatar Jan Möbius

Documentation for TypeInterface

git-svn-id: http://www.openflipper.org/svnrepo/OpenFlipper/branches/Free@11067 383ad7c9-94d9-4d36-a494-682f7c89f535
parent db0da042
......@@ -46,7 +46,7 @@
#include <OpenFlipper/BasePlugin/RPCWrappers.hh>
/** \file RPCInterfacePage.hh
/** \file RPCInterface.hh
*
* Interface for calling functions across plugins. \ref RPCInterfacePage
*/
......
......@@ -46,75 +46,32 @@
#include <OpenFlipper/common/Types.hh>
/** \file TypeInterface.hh
*
* Interface for registering types in OpenFlipper. \ref typeInterfacePage
*/
/** \brief Interface class for type definitions
*
* This interface is used to register new types in OpenFlipper. The type plugins are loaded before all other plugins.
* They have only the registerType function which registers the type to the core. The type itself has to be
* defined in the ObjectTypes subdirectory.
*
* \section TypeExample Example using custom data types
*
* Adding a custom data type to %OpenFlipper needs the following requirements in order to work:
*
* - The definition of the typeId constant, e.g.:
* \code
* #define DATA_MY_DATA typeId("MyDataType")
* \endcode
* Note: Your data type is then referenced as DATA_MY_DATA during runtime.
* - The specification of an object class for your object type that is derived from
* BaseObjectData.
* - The specification of helper functions (usually within the PluginFunctions namespace)
* allowing the casting from BaseObjectData to your object type class.
*
* See detailed examples for each of the three points for already existing data types in
* OpenFlipperRoot/ObjectTypes.
*
* Once the object class is specified, the type plugin will be responsible for its handling including
*
* - Adding new objects to the scenegraph
* - Setting the initial name of an object
* - Etc.
*
* So, type plugins usually consist of only few lines of code. Here an example of
* a type plugin handling an example object data type as mentioned above:
*
* \code
* bool MyDataTypePlugin::registerType() {
*
* addDataType("MyDataType",tr("MyDataType"));
* setTypeIcon( "MyDataType", "myDataType.png");
*
* return true;
* }
*
* int MyDataTypePlugin::addEmpty() {
*
* // Create new object
* MyObject* object = new MyObject();
*
* object->setName( QString("My Object %1.mob").arg(objectCount) );
* object->update();
* object->show();
*
* // Tell core that an object has been added
* emit emptyObjectAdded ( object->id() );
*
* return object->id();
* }
* \endcode
*
* Now, each time a plugin emits addEmptyObject(DATA_MY_DATA), the addEmpty() function will
* add the object to the scenegraph and return the newly created object's id.
*/
*
* \n
* \ref typeInterfacePage "Detailed description"
* \n
*
* This interface is used to register new types in OpenFlipper. The type plugins are loaded before all other plugins.
* They have only the registerType function which registers the type to the core and a function to add new
* objects at runtime.
*/
class TypeInterface {
signals:
/** \brief Emit this signal if an empty object has been created
* @param _id Id of the added object
*/
virtual void emptyObjectAdded( int /*_id*/ ) {};
*
* @param _id Id of the added object
*/
virtual void emptyObjectAdded( int _id ) {};
public:
......@@ -128,20 +85,96 @@ class TypeInterface {
/** \brief Create an empty object
*
* When this slot is called you have to create an object of your supported type.
* @param _type Data type of object that will be created
* @return Id of the new Object
*/
virtual int addEmpty() = 0;
/** \brief Return your supported object type( e.g. DATA_TRIANGLE_MESH )
*
* If you support multiple datatypes you can use the bitwise or to combine them here.
* The function is used from addEmpty to check if your plugin can create an object of
* a given dataType.
* The function is used from addEmpty in the core to check if your plugin can create an object of
* a given dataType. If so, your addEmpty function will be invoked to create it.
*/
virtual DataType supportedType() = 0;
};
/** \page typeInterfacePage Type Interface
\n
\image html TypeInterface.png
\n
This interface is used to register new types in OpenFlipper. The type plugins are loaded before all other plugins.
They have only the registerType function which registers the type to the core and a function to create objects
of the new type. The type itself has to be defined in the ObjectTypes subdirectory.
\section TypeExample Example using custom data types
Adding a custom data type to %OpenFlipper needs the following requirements in order to work:
- The definition of the typeId constant, e.g.:
\code
#define DATA_MY_DATA typeId("MyDataType")
\endcode
Note: Your data type is then referenced as DATA_MY_DATA during runtime.
- The specification of an object class for your object type that is derived from
BaseObjectData.
- The specification of helper functions (usually within the PluginFunctions namespace)
allowing the casting from BaseObjectData to your object type class.
See detailed examples for each of the three points for already existing data types in
OpenFlipperRoot/ObjectTypes.
Once the object class is specified, the type plugin will be responsible for its handling including
- Adding new objects to the scenegraph
- Setting the initial name of an object
- Etc.
So, type plugins usually consist of only few lines of code. Here an example of
a type plugin handling an example object data type as mentioned above:
\code
bool MyDataTypePlugin::registerType() {
addDataType("MyDataType",tr("MyDataType"));
setTypeIcon( "MyDataType", "myDataType.png");
return true;
}
int MyDataTypePlugin::addEmpty() {
// Create new object
MyObject* object = new MyObject();
object->setName( QString("My Object %1.mob").arg(objectCount) );
object->update();
object->show();
// Tell core that an object has been added
emit emptyObjectAdded ( object->id() );
return object->id();
}
\endcode
Now, each time a plugin emits addEmptyObject(DATA_MY_DATA), the addEmpty() function will
add the object to the scenegraph and return the newly created object's id.
To use the TypeInterface:
<ul>
<li> include TypeInterface.hh in your plugins header file
<li> derive your plugin from the class TypeInterface
<li> add Q_INTERFACES(TypeInterface) to your plugin class
<li> Implement all slots of this Interface
</ul>
*/
Q_DECLARE_INTERFACE(TypeInterface,"OpenFlipper.TypeInterface/1.1")
#endif // TYPEINTERFACE_HH
......@@ -65,7 +65,6 @@ PickingInterface
ProcessInterface
SecurityInterface
TextureInterface
TypeInterface
ViewInterface
ViewModeInterface
......@@ -105,11 +104,6 @@ Handle mouse picking in your plugin ( PickingInterface )
Provides functions to read and write custom filetypes ( FileInterface )
\subsection TypePlugin Type Interface
\image html TypeInterface.png
Allows plugins to specify custom data types and makes them available
to other plugins ( TypeInterface )
\subsection ViewModePlugin View Mode Interface
\image html ViewModeInterface.png
......@@ -176,6 +170,12 @@ Provides a function to add toolbar buttons. ( \ref toolbarInterfacePage )
/** \page pluginInterfacesDataHandling Object and Data Handling
This page shows interfaces for controlling and adding Objects.
\subpage typeInterfacePage
\image html TypeInterface.png
Allows plugins to specify custom data types and makes them available
to other plugins ( \ref typeInterfacePage ).
*/
......
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