Commit 2add4306 authored by Jan Möbius's avatar Jan Möbius

Moved doc pages for interfaces to the end and started baseInterface documentation page

git-svn-id: http://www.openflipper.org/svnrepo/OpenFlipper/branches/Free@10981 383ad7c9-94d9-4d36-a494-682f7c89f535
parent 6c88cfa4
......@@ -43,11 +43,17 @@
#ifndef BASEINTERFACE_HH
#define BASEINTERFACE_HH
#include <QtGui>
#include <QMenuBar>
#include <OpenFlipper/common/Types.hh>
#include <QtGui>
#include <QMenuBar>
#include <OpenFlipper/common/Types.hh>
/** \brief Interface class from which all plugins have to be created.
/** \file BaseInterface.hh
*
* OpenFlippers main plugin Interface \ref baseInterfacePage.
*/
/** \brief Interface class from which all plugins have to be created.
*
* You have to implement at least name and description for your plugin.
* All other functions and signals are optional. If you want to implement or use
......@@ -268,6 +274,14 @@ class BaseInterface {
};
/** \page baseInterfacePage Base Interface
The BaseInterface has to be used by every plugin in OpenFlipper. As the minimum a plugin
has to implement the BaseInterface::name() and BaseInterface::description() functions from this interface.
*/
Q_DECLARE_INTERFACE(BaseInterface,"OpenFlipper.BaseInterface/1.0")
#endif // BASEINTERFACE_HH
......@@ -70,6 +70,82 @@ enum ContextMenuType {
};
/** \brief Interface class for creating custom context menus
*
* \ref contextmenuInterfacePage "Detailed description"
* \n
* \n
* Using this interface you can create custom context menus for your plugin. You
* can choose between context menus for objects, nodes or the background.\n
* Before a menu of the requested type is shown, an update function for the specific type
* will be invoked by the core.
* You have to create a QAction. The signals and slots of your actions have to be connected
* to your plugin. Just connect them as usual. Only visibility of the menu is handled
* by the core. You can also add submenus to the context menus. Just add the action for
* the menu ( menu->menuAction() )
*/
class ContextMenuInterface {
public :
/// Destructor
virtual ~ContextMenuInterface() {};
signals:
/** \brief Add an entry for a context Menu
*
* Create an Action (Can also be the action of a Menu) and register this menu as a context menu to the core.
* This Action will be visible when you rightclick in the viewer widget on an item
* of the given context menu type. You can add a whole menu here by adding the action:
* menu->menuAction() of your own menu.
* @param _menu Pointer to the new Action
*/
virtual void addContextMenuItem(QAction* /*_action*/ , ContextMenuType /*_type*/) {};
/** \brief Add an entry for a context Menu
*
* Create an action (Can also be the action of a Menu) and register this action as a context menu entry to the core.
* This Action will only be visible if the picked object is of the given datatype.
* To support multiple object types with your menu, you can emit this signal multiple
* times with the same action but different DataTypes. You can add a whole Menu here by adding the action:
* menu->menuAction()
*
* @param _action Pointer to the new action
* @param _objectType Type of the picked object
* @param _type Type of the context Menu ( See ContextMenuType )
*/
virtual void addContextMenuItem(QAction* /*_action*/ ,DataType /*_objectType*/ , ContextMenuType /*_type*/ ) {};
private slots:
/** When the main application requests a context menu, this slot is called before showing the window.
* If an object is picked the id will be given in this call so you can change the contents of your menu
* depending on the given object.
* @param _objectId id of the object
*/
virtual void slotUpdateContextMenu( int /*_objectId*/ ) {};
/** When the main application requests a context menu, this slot is called before showing the window.
* This slot will be called indicating that a scenegraph node not belonging to an object
* has been picked.
* The id of the node is given as a parameter
* @param _node id of the picked node
*/
virtual void slotUpdateContextMenuNode( int /*_nodeId*/ ) {};
/** When the main application requests a context menu, this slot is called before showing the window.
* This slot will be called indicating thatthe background has been picked.
* The id of the node is given as a parameter
* @param _node id of the picked node
*/
virtual void slotUpdateContextMenuBackground( ) {};
};
/** \page contextmenuInterfacePage Context Menu Interface
\image html ContextMenuInterface.png
\n
......@@ -89,7 +165,7 @@ To use the ContextMenuInterface:
</ul>
Usually you should implement the initializePlugin() function from BaseInterface. In this function you can setup
Usually you should implement the BaseInterface::initializePlugin() function from BaseInterface. In this function you can setup
your menus.\n
You have to create a QAction. The signals and slots of your actions have to be connected
......@@ -99,7 +175,7 @@ the menu ( menu->menuAction() )
Before a menu of the requested type is shown, an update function for the specific type
will be invoked by the core depending on your type of context menu
( slotUpdateContextMenu(), slotUpdateContextMenuNode(), slotUpdateContextMenuBackground() ).
( ContextMenuInterface::slotUpdateContextMenu(), ContextMenuInterface::slotUpdateContextMenuNode(), ContextMenuInterface::slotUpdateContextMenuBackground() ).
In this function you can update entries based on the object that was clicked on. The id of the node
or the object is provided by these update functions.
......@@ -120,14 +196,14 @@ void ExamplePlugin::initializePlugin()
// QAction* menuAction_
menuAction_ = contextMenu_->addAction( tr("All Mesh vertices") );
menuAction->setToolTip(tr("Select all"));
// Add the new menu to OpenFlippers context menu fot objects
// Show the context menu for triangle meshes
emit addContextMenuItem(contextMenu_->menuAction() , DATA_TRIANGLE_MESH , CONTEXTOBJECTMENU );
// Show the context menu for poly meshes meshes
emit addContextMenuItem(contextMenu_->menuAction() , DATA_POLY_MESH , CONTEXTOBJECTMENU );
}
}
// Example function to update the context menu based on the given object id
......@@ -159,80 +235,6 @@ your plugin. Therefore the embedding of your menus into the OpenFlippers context
*/
/** \brief Interface class for creating custom context menus
*
* \ref contextmenuInterfacePage "Detailed description"
* \n
* \n
* Using this interface you can create custom context menus for your plugin. You
* can choose between context menus for objects, nodes or the background.\n
* Before a menu of the requested type is shown, an update function for the specific type
* will be invoked by the core.
* You have to create a QAction. The signals and slots of your actions have to be connected
* to your plugin. Just connect them as usual. Only visibility of the menu is handled
* by the core. You can also add submenus to the context menus. Just add the action for
* the menu ( menu->menuAction() )
*/
class ContextMenuInterface {
public :
/// Destructor
virtual ~ContextMenuInterface() {};
signals:
/** \brief Add an entry for a context Menu
*
* Create an Action (Can also be the action of a Menu) and register this menu as a context menu to the core.
* This Action will be visible when you rightclick in the viewer widget on an item
* of the given context menu type. You can add a whole menu here by adding the action:
* menu->menuAction() of your own menu.
* @param _menu Pointer to the new Action
*/
virtual void addContextMenuItem(QAction* /*_action*/ , ContextMenuType /*_type*/) {};
/** \brief Add an entry for a context Menu
*
* Create an action (Can also be the action of a Menu) and register this action as a context menu entry to the core.
* This Action will only be visible if the picked object is of the given datatype.
* To support multiple object types with your menu, you can emit this signal multiple
* times with the same action but different DataTypes. You can add a whole Menu here by adding the action:
* menu->menuAction()
*
* @param _action Pointer to the new action
* @param _objectType Type of the picked object
* @param _type Type of the context Menu ( See ContextMenuType )
*/
virtual void addContextMenuItem(QAction* /*_action*/ ,DataType /*_objectType*/ , ContextMenuType /*_type*/ ) {};
private slots:
/** When the main application requests a context menu, this slot is called before showing the window.
* If an object is picked the id will be given in this call so you can change the contents of your menu
* depending on the given object.
* @param _objectId id of the object
*/
virtual void slotUpdateContextMenu( int /*_objectId*/ ) {};
/** When the main application requests a context menu, this slot is called before showing the window.
* This slot will be called indicating that a scenegraph node not belonging to an object
* has been picked.
* The id of the node is given as a parameter
* @param _node id of the picked node
*/
virtual void slotUpdateContextMenuNode( int /*_nodeId*/ ) {};
/** When the main application requests a context menu, this slot is called before showing the window.
* This slot will be called indicating thatthe background has been picked.
* The id of the node is given as a parameter
* @param _node id of the picked node
*/
virtual void slotUpdateContextMenuBackground( ) {};
};
Q_DECLARE_INTERFACE(ContextMenuInterface,"OpenFlipper.ContextMenuInterface/1.0")
#endif // CONTEXTMENUINTERFACE_HH
......@@ -62,6 +62,58 @@
* Interface for adding per plugin toolboxes to OpenFlippers UI.\ref menuInterfacePage
*/
/** \brief Interface for all plugins which provide entries to the main menubar
*
* \ref menuInterfacePage "Detailed description"
* \n
* \n
* To add custom menus or actions to the menubar, you have to use this interface class. Create
* your own QMenu or QAction and emit addMenubarAction to add it to one of the menubar toplevel menus.
* You can also get a pointer to one existing toplevel menu or create a new one with the getMenubarMenu
* function. You can connect the signals and slots for your menu or action inside the plugin.
*/
class MenuInterface {
public :
/// Destructor
virtual ~MenuInterface() {};
signals:
/** \brief Get a existing toplevel menu pointer or create a new one
*
* Checks if a toplevel menu is present and creates one if needed \n
*
* @param _name Menu name (see FILEMENU/VIEWMENU/TOOLSMENU example defines or use other QStrings )
* @param _menu The returned toplevel menu
* @param _create Should a new menu be created if id doesn't exist
*/
virtual void getMenubarMenu (QString /*_name*/, QMenu *& /*_menu*/, bool /*_create*/) {};
/** \brief Adds an action to the menubar
*
* Add an action to one of the menubar toplevel menus \n
* \n
* Example : \n
* \code
* QMenu *colorMenu = new QMenu(tr("&Colors"));
* emit addMenubarAction( colorMenu->menuAction(), TOOLSMENU );
* \endcode
*
* All actions or sub actions can be freely controlled by yourself. You have
* to connect the required signals and slots to your plugin.
*
* @param _action Pointer to the new action
* @param _name Name of the menu
*/
virtual void addMenubarAction(QAction* /*_action*/, QString /*_name*/ ) {};
};
/** \page menuInterfacePage Menu Interface
\image html MenuInterface.png
\n
......@@ -76,7 +128,7 @@ To use the MenuInterface:
<li> And add the signals or slots you want to use to your plugin class (You don't need to implement all of them)
</ul>
Usually you should implement the initializePlugin() function from BaseInterface. In this function you can setup
Usually you should implement the BaseInterface::initializePlugin() function from BaseInterface. In this function you can setup
your menus.
The following code shows a simple example to create a menu entry in the file menu.
......@@ -115,56 +167,6 @@ your plugin. Therefore the embedding of your menus into the OpenFlippers menu li
*/
/** \brief Interface for all plugins which provide entries to the main menubar
*
* \ref menuInterfacePage "Detailed description"
* \n
* \n
* To add custom menus or actions to the menubar, you have to use this interface class. Create
* your own QMenu or QAction and emit addMenubarAction to add it to one of the menubar toplevel menus.
* You can also get a pointer to one existing toplevel menu or create a new one with the getMenubarMenu
* function. You can connect the signals and slots for your menu or action inside the plugin.
*/
class MenuInterface {
public :
/// Destructor
virtual ~MenuInterface() {};
signals:
/** \brief Get a existing toplevel menu pointer or create a new one
*
* Checks if a toplevel menu is present and creates one if needed \n
*
* @param _name Menu name (see FILEMENU/VIEWMENU/TOOLSMENU example defines or use other QStrings )
* @param _menu The returned toplevel menu
* @param _create Should a new menu be created if id doesn't exist
*/
virtual void getMenubarMenu (QString /*_name*/, QMenu *& /*_menu*/, bool /*_create*/) {};
/** \brief Adds an action to the menubar
*
* Add an action to one of the menubar toplevel menus \n
* \n
* Example : \n
* \code
* QMenu *colorMenu = new QMenu(tr("&Colors"));
* emit addMenubarAction( colorMenu->menuAction(), TOOLSMENU );
* \endcode
*
* All actions or sub actions can be freely controlled by yourself. You have
* to connect the required signals and slots to your plugin.
*
* @param _action Pointer to the new action
* @param _name Name of the menu
*/
virtual void addMenubarAction(QAction* /*_action*/, QString /*_name*/ ) {};
};
Q_DECLARE_INTERFACE(MenuInterface,"OpenFlipper.MenuInterface/1.0")
#endif // MENUBARINTERFACE_HH
......@@ -53,45 +53,7 @@
* Interface for adding per plugin toolboxes to OpenFlippers UI.\ref toolboxInterfacePage
*/
/** \page toolboxInterfacePage Toolbox Interface
\image html ToolboxInterface.png
The ToolboxInterface can be used by plugins to add widgets to the list of toolboxes in OpenFlippers
UI. The toolboxes are located left or right of the gl viewer (See image).
The list can be hidden by pressing Ctrl + t.
To use the ToolboxInterface:
<ul>
<li> include ToolboxInterface.hh in your plugins header file
<li> derive your plugin from the class ToolboxInterface
<li> add Q_INTERFACES(ToolboxInterface) to your plugin class
<li> And add the signals or slots you want to use to your plugin class (You don't need to implement all of them)
</ul>
Usually you should implement the initializePlugin() function from BaseInterface. In this function you can setup
your toolbox ( some kind of QWidget, can also be any widget created with qt-designer). Optionally you can also
add an icon to the toolbox.
The following code shows a simple example to create an empty toolbox.
\code
void SmootherPlugin::initializePlugin()
{
// Create the Toolbox Widget
QWidget* toolBox = new QWidget();
// Create an icon which is shown along with the toolbox
QIcon* toolIcon = new QIcon(OpenFlipper::Options::iconDirStr()+OpenFlipper::Options::dirSeparator()+"smoother1.png");
// Tell the core to include the new toolbox widget with the name Simple Smoother, a pointer to the widget and a pointer to the icon
emit addToolbox( tr("Simple Smoother") , toolBox, toolIcon );
}
\endcode
Signals and slots of your toolbox (e.g. from a QPushButton inside it) can be directly connected to signals and slots in
your plugin. Therefore the embedding of the widget into the toolbox list is fully transparent.
*/
......@@ -134,6 +96,48 @@ class ToolboxInterface {
virtual void addToolbox( QString /* _name */ , QWidget* /*_widget*/, QIcon* /*_icon*/) {};
};
/** \page toolboxInterfacePage Toolbox Interface
\image html ToolboxInterface.png
The ToolboxInterface can be used by plugins to add widgets to the list of toolboxes in OpenFlippers
UI. The toolboxes are located left or right of the gl viewer (See image).
The list can be hidden by pressing Ctrl + t.
To use the ToolboxInterface:
<ul>
<li> include ToolboxInterface.hh in your plugins header file
<li> derive your plugin from the class ToolboxInterface
<li> add Q_INTERFACES(ToolboxInterface) to your plugin class
<li> And add the signals or slots you want to use to your plugin class (You don't need to implement all of them)
</ul>
Usually you should implement the BaseInterface::initializePlugin() function from BaseInterface. In this function you can setup
your toolbox ( some kind of QWidget, can also be any widget created with qt-designer). Optionally you can also
add an icon to the toolbox.
The following code shows a simple example to create an empty toolbox.
\code
void SmootherPlugin::initializePlugin()
{
// Create the Toolbox Widget
QWidget* toolBox = new QWidget();
// Create an icon which is shown along with the toolbox
QIcon* toolIcon = new QIcon(OpenFlipper::Options::iconDirStr()+OpenFlipper::Options::dirSeparator()+"smoother1.png");
// Tell the core to include the new toolbox widget with the name Simple Smoother, a pointer to the widget and a pointer to the icon
emit addToolbox( tr("Simple Smoother") , toolBox, toolIcon );
}
\endcode
Signals and slots of your toolbox (e.g. from a QPushButton inside it) can be directly connected to signals and slots in
your plugin. Therefore the embedding of the widget into the toolbox list is fully transparent.
*/
Q_DECLARE_INTERFACE(ToolboxInterface,"OpenFlipper.ToolboxInterface/1.1")
#endif // TOOLBOXINTERFACE_HH
......@@ -32,6 +32,13 @@ The core application will only use the slots you define in the plugins header fi
If you recognize that an interface function of your plugin is not called, check if it is defined correctly in your plugin
class and the signature is the same as in the interface.\n
\section pluginInterfacesBaseInterface OpenFlipper Base Interface
\subpage baseInterfacePage
All plugins in OpenFlipper have to implement some basic functions from BaseInterface. They are used to integrate and manage
the plugins by the core application. See \ref baseInterfacePage for details.
\section pluginInterfacesUIOverview Available Interfaces for controlling the User Interface
This section gives an overview over the available interfaces which control OpenFlippers User interface.
......
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