Commit 6c88cfa4 authored by Jan Möbius's avatar Jan Möbius
Browse files

Documentation for context menu interface

git-svn-id: http://www.openflipper.org/svnrepo/OpenFlipper/branches/Free@10980 383ad7c9-94d9-4d36-a494-682f7c89f535
parent 712b8e49
...@@ -48,27 +48,132 @@ ...@@ -48,27 +48,132 @@
#include <QMenuBar> #include <QMenuBar>
#include <OpenFlipper/common/Types.hh> #include <OpenFlipper/common/Types.hh>
enum ContextMenuType {
/// The Menu will be shown when an object was picked /** \file ContextMenuInterface.hh
CONTEXTOBJECTMENU, *
/// The Menu will be shown when a node was picked * Interface for adding context menus to OpenFlippers UI from a plugin.\ref contextmenuInterfacePage
CONTEXTNODEMENU, */
/// The Menu will be shown when the background was picked
CONTEXTBACKGROUNDMENU
/** Enum to specify the type of context menus
*/
enum ContextMenuType {
/// The Menu will be shown when an object was picked
CONTEXTOBJECTMENU,
/// The Menu will be shown when a node was picked
CONTEXTNODEMENU,
/// The Menu will be shown when the background was picked
CONTEXTBACKGROUNDMENU
}; };
/** \brief Interface class for creating custom context menus
/** \page contextmenuInterfacePage Context Menu Interface
\image html ContextMenuInterface.png
\n
The ContextMenuInterface can be used by plugins to add menu entries to OpenFlippers
UI. The entries will be added to OpenFlippers contextMenus in the glView (see image).
You can choose between context menus for objects, nodes or the background.\n
The given context menu entries will be shown when the user right clicks on the corresponding
primitive (node,object) in the gl viewer.
To use the ContextMenuInterface:
<ul>
<li> include ContextMenuInterface.hh in your plugins header file
<li> derive your plugin from the class ContextMenuInterface
<li> add Q_INTERFACES(ContextMenuInterface) 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 menus.\n
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() )
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() ).
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.
The following code shows a simple example to create a menu entry in the context menu.
\code
// Setup the menus in initialize plugins
void ExamplePlugin::initializePlugin()
{
// create a global QMenu in the plugin that contains our menu
// in the header is:
// QMenu* contextMenu_
contextMenu_ = new QMenu(tr("Select"));
// Create a menu action called all in the Selection context menu
// in the header is:
// 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
void ExamplePlugin::slotUpdateContextMenu( int _objectId ){
// Get the corresponding object of the given id or return
BaseObjectData* object = 0;
if ( !PluginFunctions::getObject( _objectId, object ) ) {
return;
}
// If its a triangle mesh, rename the to triangle mesh selection
if (object->dataType( DATA_TRIANGLE_MESH ) )
menuAction_->setText("All Triangle mesh vertices");
// If its a triangle mesh, rename the to poly mesh selection
if ( object->dataType( DATA_POLY_MESH ) )
menuAction_->setText("All Triangle mesh vertices");
}
}
\endcode
Signals and slots of your menus (e.g. from an action inside it) can be directly connected to signals and slots in
your plugin. Therefore the embedding of your menus into the OpenFlippers context menu list is fully transparent.
*/
/** \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 * 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 * 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 * Before a menu of the requested type is shown, an update function for the specific type
* will be invoked by the core. * will be invoked by the core.
* You have to create a QAction. The signals and slots of your actions have to be connected * 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 * 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 * by the core. You can also add submenus to the context menus. Just add the action for
* the menu ( menu->menuAction() ) * the menu ( menu->menuAction() )
*/ */
class ContextMenuInterface { class ContextMenuInterface {
public : public :
......
...@@ -77,7 +77,7 @@ To use the MenuInterface: ...@@ -77,7 +77,7 @@ To use the MenuInterface:
</ul> </ul>
Usually you should implement the initializePlugin() function from BaseInterface. In this function you can setup Usually you should implement the initializePlugin() function from BaseInterface. In this function you can setup
your menus your menus.
The following code shows a simple example to create a menu entry in the file menu. The following code shows a simple example to create a menu entry in the file menu.
\code \code
......
/** \page interfaces Plugin Interfaces /** \page interfaces Plugin Interfaces
*
* \section pluginInterfacesIntro Introduction \section pluginInterfacesIntro Introduction
*
* OpenFlipper provides a flexible plugin interface. Plugins can implement various interfaces.\n OpenFlipper provides a flexible plugin interface. Plugins can implement various interfaces.\n
*
* Each interface provides special signals/slots or functions to communicate with the core or Each interface provides special signals/slots or functions to communicate with the core or
* to react on special events. The most important interface is the BaseInterface. This Interface to react on special events. The most important interface is the BaseInterface. This Interface
* provides the core functionality for the plugin. E.g. loading the plugin, specifying its name provides the core functionality for the plugin. E.g. loading the plugin, specifying its name
* and basic communication regarding object changes or view updates ( See BaseInterface for further details).\n and basic communication regarding object changes or view updates ( See BaseInterface for further details).\n
*
* Additional functionality is provided by the other interfaces. For user interaction one typically uses the Additional functionality is provided by the other interfaces. For user interaction one typically uses the
* MouseInterface or KeyInterface which will provide events based on mouse or keyboard interaction.\n MouseInterface or KeyInterface which will provide events based on mouse or keyboard interaction.\n
*
* The user interface of OpenFlipper can also be used by plugins. The MenubarInterface provides functions to The user interface of OpenFlipper can also be used by plugins. The MenubarInterface provides functions to
* add additional icons to the menubar while the ToolboxInterface can add widgets to the toolbox on add additional icons to the menubar while the ToolboxInterface can add widgets to the toolbox on
* the right of the OpenFlipper screen. the right of the OpenFlipper screen.
*
* \section pluginInterfacesUsage Usage of plugin interfaces \section pluginInterfacesUsage Usage of plugin interfaces
*
* To use functions from one of the interfaces you have to do the following steps: To use functions from one of the interfaces you have to do the following steps:
* <ul> <ul>
* <li> Include the interface header file in your plugins header file <li> Include the interface header file in your plugins header file
* <li> derive your plugin from the Interface class defined in the interface header file <li> derive your plugin from the Interface class defined in the interface header file
* <li> add Q_INTERFACES( InterfaceName ) macro to your plugin class containing only the name of the interface to be used <li> add Q_INTERFACES( InterfaceName ) macro to your plugin class containing only the name of the interface to be used
* <li> Add the signature of the signals you want to use to the signals of your class definition. <li> Add the signature of the signals you want to use to the signals of your class definition.
* <li> Add the signature of a slot you want to implement to the \b private \b slots of your class definition. <li> Add the signature of a slot you want to implement to the \b private \b slots of your class definition.
* </ul> </ul>
* It is not necessary to implement all signals or slots from one of the interfaces (Except some functions from BaseInterface). It is not necessary to implement all signals or slots from one of the interfaces (Except some functions from BaseInterface).
* The core application will only use the slots you define in the plugins header file and ignore all other functions.\n The core application will only use the slots you define in the plugins header file and ignore all other functions.\n
*
* If you recognize that an interface function of your plugin is not called, check if it is defined correctly in your plugin 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 class and the signature is the same as in the interface.\n
*
* \section pluginInterfacesOverview Available Interfaces \section pluginInterfacesUIOverview Available Interfaces for controlling the User Interface
*
* This section gives an overview over the available interfaces in OpenFlipper. This section gives an overview over the available interfaces which control OpenFlippers User interface.
*
* \subsection BasePlugin Base Interface \subpage contextmenuInterfacePage
* This is the Basic plugin Interface. All Plugins have to provide at least this interface. It offers plugin \image html ContextMenuInterface.png
* name and some important Signals and slots which will be called by the main application. See BaseInterface Add context menu entries in your plugin. ( \ref contextmenuInterfacePage )
* for details. \n
*
* \subsection KeyPlugin Keyboard Interface \subpage menuInterfacePage
* \image html keyInterface.png \image html MenuInterface.png
* You have to provide this interface if you want to get key events in your plugin ( KeyInterface ).\n Provides a function to create entries in the menubar ( \ref menuInterfacePage ).
* \n
*
* \subsection MousePlugin Mouse Interface \subpage toolboxInterfacePage
* \image html mouseInterface.png \image html ToolboxInterface.png
* This interface is used to deliver mouse events to a plugin ( MouseInterface ).\n Provides functions to create a separate widget in the toolbox on the right ( \ref toolboxInterfacePage ).
* \n
*
* \subsection LoadSavePlugin Load / Save Interface \section pluginInterfacesOtherOverview Available Interfaces for controlling other functions
* \image html loadSaveInterface.png
* Provides functions to handle mesh files and load / unload geometry This section gives an overview over the available interfaces which control other parts of OpenFlipper.
* objects into the scene graph ( LoadSaveInterface ).
* \subsection BasePlugin Base Interface
* This is the Basic plugin Interface. All Plugins have to provide at least this interface. It offers plugin
* \subsection ToolbarPlugin Toolbar Interface name and some important Signals and slots which will be called by the main application. See BaseInterface
* \image html ToolbarInterface.png for details.
* Provides a function to add toolbar buttons. ( ToolbarInterface )
* \subsection KeyPlugin Keyboard Interface
* \image html keyInterface.png
* \subsection ContextMenu Context Menu Interface You have to provide this interface if you want to get key events in your plugin ( KeyInterface ).\n
* \image html ContextMenuInterface.png
* Add context menu entries in your plugin. ( ContextMenuInterface )
* \subsection MousePlugin Mouse Interface
* \image html mouseInterface.png
* \subpage menuInterfacePage This interface is used to deliver mouse events to a plugin ( MouseInterface ).\n
* \image html MenuInterface.png
* Provides a function to create entries in the menubar ( \ref menuInterfacePage ).
* \subsection LoadSavePlugin Load / Save Interface
* \image html loadSaveInterface.png
* \subpage toolboxInterfacePage Provides functions to handle mesh files and load / unload geometry
* \image html ToolboxInterface.png objects into the scene graph ( LoadSaveInterface ).
* Provides functions to create a separate widget in the toolbox on the right ( \ref toolboxInterfacePage ).
* \n
* \subsection ToolbarPlugin Toolbar Interface
* \subpage loggingInterfacePage \image html ToolbarInterface.png
* \image html LoggingInterface.png Provides a function to add toolbar buttons. ( ToolbarInterface )
* This is an Interface for Logging to the included log widget. You can log to different levels
* (LOGOUT,LOGWARN,LOGERR,LOGINFO) ( \ref loggingInterfacePage ).
* \n \subpage loggingInterfacePage
* \image html LoggingInterface.png
* \subsection TexturePlugin Texture Interface This is an Interface for Logging to the included log widget. You can log to different levels
* \image html TextureInterface.png (LOGOUT,LOGWARN,LOGERR,LOGINFO) ( \ref loggingInterfacePage ).
* Allows your plugin to provide a texture. ( TextureInterface ) \n
*
* \subsection TexturePlugin Texture Interface
* \subsection PickingPlugin Mouse Picking / Pick Modes \image html TextureInterface.png
* \image html PickingInterface.png Allows your plugin to provide a texture. ( TextureInterface )
* Handle mouse picking in your plugin ( PickingInterface )
*
* \subsection PickingPlugin Mouse Picking / Pick Modes
* \subsection RPCPlugin RPC Interface \image html PickingInterface.png
* \image html RPCInterface.png Handle mouse picking in your plugin ( PickingInterface )
* This interface is used to call functions across different plugins ( RPCInterface ).
*
* \subsection RPCPlugin RPC Interface
* \subsection FilePlugin File Interface \image html RPCInterface.png
* \image html FileInterface.png This interface is used to call functions across different plugins ( RPCInterface ).
* Provides functions to read and write custom filetypes ( FileInterface )
*
* \subsection FilePlugin File Interface
* \subsection TypePlugin Type Interface \image html FileInterface.png
* \image html FileInterface.png Provides functions to read and write custom filetypes ( FileInterface )
* Allows plugins to specify custom data types and makes them available
* to other plugins ( TypeInterface )
* \subsection TypePlugin Type Interface
* \image html FileInterface.png
* \subsection ViewModePlugin View Mode Interface Allows plugins to specify custom data types and makes them available
* \image html FileInterface.png to other plugins ( TypeInterface )
* Specify own view modes ( ViewModeInterface )
*
* \subsection ViewModePlugin View Mode Interface
* \subsection ViewPlugin View Interface \image html FileInterface.png
* \image html ViewInterface.png Specify own view modes ( ViewModeInterface )
* This interface is used to add additional view widgets ( ViewInterface ).
*
* \subsection ViewPlugin View Interface
* \subsection ScriptPlugin Script Interface \image html ViewInterface.png
* \image html ScriptInterface.png This interface is used to add additional view widgets ( ViewInterface ).
* For plugins who provide scriptable functions ( ScriptInterface )
*
* \subsection ScriptPlugin Script Interface
* \subsection StatusPlugin Status Bar Interface \image html ScriptInterface.png
* \image html StatusbarInterface.png For plugins who provide scriptable functions ( ScriptInterface )
* This interface is used to display messages in the status bar ( StatusbarInterface )
*
* \subsection StatusPlugin Status Bar Interface
* \subsection OptionsPlugin Options Interface \image html StatusbarInterface.png
* \image html OptionsInterface.png This interface is used to display messages in the status bar ( StatusbarInterface )
* This Interface is used by plugins which will provide their own options by
* integrating its own options widget into OpenFlipper's options window. ( OptionsInterface )
* \subsection OptionsPlugin Options Interface
* \image html OptionsInterface.png
* \subsection BackupPlugin Backup Interface This Interface is used by plugins which will provide their own options by
* \image html BackupInterface.png integrating its own options widget into OpenFlipper's options window. ( OptionsInterface )
* Use this interface to backup data ( BackupInterface )
*
* \subsection BackupPlugin Backup Interface
* \subsection INIPlugin Use Inifiles to store information \image html BackupInterface.png
* \image html INIInterface.png Use this interface to backup data ( BackupInterface )
* Receive an event if an ini file is opened by the application. ( INIInterface )\n
*/
\subsection INIPlugin Use Inifiles to store information
\image html INIInterface.png
Receive an event if an ini file is opened by the application. ( INIInterface )\n
*/
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