diff --git a/Documentation/Doxygen/BlueBerry/BlueBerryExtensionPointsIntro.dox b/Documentation/Doxygen/BlueBerry/BlueBerryExtensionPointsIntro.dox new file mode 100644 index 0000000000..3c43997c9a --- /dev/null +++ b/Documentation/Doxygen/BlueBerry/BlueBerryExtensionPointsIntro.dox @@ -0,0 +1,34 @@ +/** + +\page BlueBerryExampleExtensionPoint Extension Points + +\brief A minimal applictaion that definines an extension point and collects extensions. + +-# \subpage IntroductionExtensionPoints "Introduction" +-# \subpage ExtensionPointDefinition "Extension Point Definition" +-# \subpage ExtensionContribution "Extension Contribution" + +\page IntroductionExtensionPoints Introduction: Extension Point/Extension Concept + +The BlueBerry application framework provides the concept of extension points and extensions. The main goal is to allow the extension of functionality of a plugin (based on the contract defined by the extension point) by several other plugins. Both the extension point and the extension are defined in the according plugin.xml. + +\image html ExtensionPoints.png "Extension Point concept" + +\section SimpleExample Why Extension Points? +In the following simple example we have a plugin 'a' and 'b' with two classes 'A' and 'B' in these plugins. + +\image html ExtensionPointEx.png "Simple Example" + +Plugin 'a' uses the extension point mechanism and creates an extension point that can be extended by other plugins. Now if class 'A' reaches a part that can be extended it asks 'a' if another plugin is registered. If that's the case the functionality of the plugin 'b' that is defined in class 'B' is executed. +A plugin can therefore be arbitrary extended. + +\section Examples Examples + +The two following example plugins describe the usage of the BlueBerry Extension Points. One example defines an extension point and the other example extends the created extension point. + +\li \ref org_mitk_example_gui_selectionservicemitk +\li \ref org_mitk_example_gui_selectionserviceqt + +[\ref BlueBerryExampleExtensionPoint] [Next: \ref ExtensionPointDefinition] [\ref BlueBerryExamples] + +*/ diff --git a/Documentation/Doxygen/BlueBerry/BlueBerrySelectionServiceIntro.dox b/Documentation/Doxygen/BlueBerry/BlueBerrySelectionServiceIntro.dox index ad31604623..860c7cc20d 100644 --- a/Documentation/Doxygen/BlueBerry/BlueBerrySelectionServiceIntro.dox +++ b/Documentation/Doxygen/BlueBerry/BlueBerrySelectionServiceIntro.dox @@ -1,40 +1,40 @@ /** \page BlueBerrySelectionServiceIntro Selection Service -# \subpage IntroductionSelectionService "Introduction" -# \subpage BlueBerryExampleSelectionServiceQt -# \subpage BlueBerryExampleSelectionServiceMitk \page IntroductionSelectionService Introduction: Selection Service Concept The selection service provided by the BlueBerry workbench allows efficient linking of different parts within the workbench window: View parts that provide additional information for particular objects and update their content automatically whenever such objects are selected somewhere in the workbench window. For example the "Properties" view in MITK applications behaves in this way: Wherever an element is selected in the workbench this view lists the properties of that element. \image html MitkSelectionService.png "DataNode properties" Other aspects of the workbench like the enablement of global actions may also depend on the current selection. Each workbench window has its own selection service instance. The service keeps track of the selection in the currently active part and propagates selection changes to all registered listeners. Such selection events occur when the selection in the current part is changed or when a different part is activated. Both can be triggered by user interaction or programmatically. \image html SelectionServiceDiagram.png "Selection Service Diagram" \section WhatCanBeSelected What can be selected? From the users point of view a selection is a set of highlighted entries in a viewer like a table or tree widget. A selection can also be a piece of text in an editor. Internally a selection is a data structure holding the model objects which corresponds to the graphical elements selected in the workbench. As pointed out before there are two fundamental different kinds of selections: \li A list of objects \li A piece of text \section Examples The following two examples describe different ways of implementing and using the provided selection services. One example is based on the Qt selection model, the other one is based on the MITK Data node selection. \li \ref org_mitk_example_gui_selectionservicemitk \li \ref org_mitk_example_gui_selectionserviceqt Knowing and using the existing selection mechanisms gives your plug-ins a clean design, smoothly integrates them into the workbench and opens them for future extensions. -[\ref ExamplePage] +[\ref BlueBerrySelectionServiceIntro] [Next: \ref BlueBerryExampleSelectionServiceQt] [\ref BlueBerryExamples] */ diff --git a/Documentation/Doxygen/BlueBerry/ExtensionPointEx.png b/Documentation/Doxygen/BlueBerry/ExtensionPointEx.png new file mode 100644 index 0000000000..404222cbc5 Binary files /dev/null and b/Documentation/Doxygen/BlueBerry/ExtensionPointEx.png differ diff --git a/Documentation/Doxygen/BlueBerry/ExtensionPoints.png b/Documentation/Doxygen/BlueBerry/ExtensionPoints.png new file mode 100644 index 0000000000..e32ddcb3f2 Binary files /dev/null and b/Documentation/Doxygen/BlueBerry/ExtensionPoints.png differ diff --git a/Examples/BlueBerryExampleLauncher/Configurations/ExtensionPointDefinition.cmake b/Examples/BlueBerryExampleLauncher/Configurations/ExtensionPointDefinition.cmake index e60be8c50a..e1493980b9 100644 --- a/Examples/BlueBerryExampleLauncher/Configurations/ExtensionPointDefinition.cmake +++ b/Examples/BlueBerryExampleLauncher/Configurations/ExtensionPointDefinition.cmake @@ -1,19 +1,19 @@ set(REQUIRED_PLUGINS org.mitk.example.gui.extensionpointdefinition org.mitk.example.gui.extensionpointcontribution ) set(DESCRIPTION -"This BlueBerry example consists of two plugins that demonstrate the use of the extension point concept. The first plugin defines an extension point and holds the GUI. The user can insert a text in a text field. The second plugin contributes an extension in the form of two classes that can change a given text to upper or lower case. +"This BlueBerry example consists of two plugins that demonstrate the use of the extension point concept. The first plugin defines an extension point and holds the GUI. The user can insert a text in a text field. The second plugin contributes an extension in the form of two classes that can change the user text to upper or lower case.

The following features are demonstrated:

See the main documentation for details." ) diff --git a/Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/documentation/doxygen/ContributionXML.png b/Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/documentation/doxygen/ContributionXML.png new file mode 100644 index 0000000000..60791cc431 Binary files /dev/null and b/Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/documentation/doxygen/ContributionXML.png differ diff --git a/Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/documentation/doxygen/DefinitionXML.png b/Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/documentation/doxygen/DefinitionXML.png new file mode 100644 index 0000000000..441fbf0451 Binary files /dev/null and b/Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/documentation/doxygen/DefinitionXML.png differ diff --git a/Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/documentation/doxygen/ExampleExtensionPoint.dox b/Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/documentation/doxygen/ExampleExtensionPoint.dox index 53739f7d4c..f1f8a1a109 100644 --- a/Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/documentation/doxygen/ExampleExtensionPoint.dox +++ b/Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/documentation/doxygen/ExampleExtensionPoint.dox @@ -1,12 +1,55 @@ /** -\page BlueBerryExampleExtensionPoint Extension Points +\page ExtensionPointDefinition Extension Point Definition --# \subpage IntroductionExtensionPoints "Introduction" --# Extension Point Definition --# Extension Contribution + This example plugin defines an extension point and collects extensions. + \image html ExtensionPointWithoutExtension.png -\page IntroductionExtensionPoints Introduction: Extension Point/Extension Concept + In this example the extension point concept is used to define an extension point and extend the plugin functionality with it. The GUI consists of a view with two group boxes. In the right box the user can insert text in an input text field. The left box is the area where extensions for this plugin are displayed. + In the plugin.xml file of this application the extension point is defined as follows: + \image html DefinitionXML.png + The according schema (\github{Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/schema/changetext.exsd,changetext.exsd}) defines attributes for extensions of this extension point like a description. + + In the view of this plugin the registry is used to find all available extensions. For each found descriptor a push button is created that holds the functionality extension. + \snippet MinimalView.cpp Collect extensions through registry + + These created push buttons are connected to the ChangeText method that alters the input text (in the way the extension defines) and outputs the changed text in another text field. + \snippet MinimalView.cpp Use extended functionality to alter input text + + The plugin can now be extened by extensions provided by other plugins. + + View complete source files: + \li \github{Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/src/internal/ChangeTextDescriptor.cpp,ChangeTextDescriptor.cpp} + \li \github{Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/src/internal/ChangeTextDescriptor.h,ChangeTextDescriptor.h} + \li \github{Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/src/internal/ChangeTextRegistry.cpp,ChangeTextRegistry.cpp} + \li \github{Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/src/internal/ChangeTextRegistry.h,ChangeTextRegistry.h} + \li \github{Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/src/internal/ExtensionPointDefinition.cpp,ExtensionPointDefinition.cpp} + \li \github{Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/src/internal/ExtensionPointDefinition.h,ExtensionPointDefinition.h} + \li \github{Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/src/internal/ExtensionPointDefinitionConstants.cpp,ExtensionPointDefinitionConstants.cpp} + \li \github{Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/src/internal/ExtensionPointDefinitionConstants.h,ExtensionPointDefinitionConstants.h} + +[\ref BlueBerryExampleExtensionPoint] [Next: \ref ExtensionContribution] [\ref BlueBerryExamples] + +\page ExtensionContribution Extension Contribution + + This example plugin holds no GUI. It just extends the Extension Point Definition plugin. + \image html ExtensionPointWithExtension.png + + Through the extension of the Extension Point Definition plugin two functionalities are added by implementing the minimal IChangeText interface of the plugin. + + In the plugin.xml file of the plugin the extensions are defined as follows: + \image html ContributionXML.png + The extension point ID in the plugin.xml matches the ID of the extension point and is therefore found by the registry as a valid extension. A description is given for each extension although the schema for the extension point allows an extension without a description (). + + The GUI now holds two buttons that change the input text of the user to upper or lower case. This is done by two simple methods. + + View complete source files: + \li \github{Examples/Plugins/org.mitk.example.gui.extensionpointcontribution/src/internal/ChangeTextToLowerCase.cpp,ChangeTextToLowerCase.cpp} + \li \github{Examples/Plugins/org.mitk.example.gui.extensionpointcontribution/src/internal/ChangeTextToLowerCase.h,ChangeTextToLowerCase.h} + \li \github{Examples/Plugins/org.mitk.example.gui.extensionpointcontribution/src/internal/ChangeTextToUpperCase.cpp,ChangeTextToUpperCase.cpp} + \li \github{Examples/Plugins/org.mitk.example.gui.extensionpointcontribution/src/internal/ChangeTextToUpperCase.h,ChangeTextToUpperCase.h} + +[\ref BlueBerryExampleExtensionPoint] [Previous: \ref ExtensionPointDefinition] [\ref BlueBerryExamples] */ diff --git a/Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/documentation/doxygen/ExtensionPointWithExtension.png b/Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/documentation/doxygen/ExtensionPointWithExtension.png new file mode 100644 index 0000000000..afd43deb91 Binary files /dev/null and b/Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/documentation/doxygen/ExtensionPointWithExtension.png differ diff --git a/Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/documentation/doxygen/ExtensionPointWithoutExtension.png b/Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/documentation/doxygen/ExtensionPointWithoutExtension.png new file mode 100644 index 0000000000..c3f6ae3fdc Binary files /dev/null and b/Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/documentation/doxygen/ExtensionPointWithoutExtension.png differ diff --git a/Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/documentation/doxygen/modules.dox b/Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/documentation/doxygen/modules.dox index 62c3b3f63e..5162e5ff62 100644 --- a/Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/documentation/doxygen/modules.dox +++ b/Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/documentation/doxygen/modules.dox @@ -1,15 +1,15 @@ /** \defgroup org_mitk_example_gui_extensionpointdefinition org.mitk.example.gui.extensionpointdefinition \ingroup MITKExamplePlugins - \brief A minimal applictaion that definines an extension point. + \brief A minimal applictaion that definines an extension point and collects extensions. */ /** \defgroup org_mitk_example_gui_extensionpointdefinition_internal Internal \ingroup org_mitk_example_gui_extensionpointdefinition \brief This subcategory includes the internal classes of the org.mitk.example.gui.extensionpointdefinition plugin. Other plugins must not rely on these classes. They contain implementation details and their interface may change at any time. We mean it. */ diff --git a/Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/src/internal/MinimalView.cpp b/Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/src/internal/MinimalView.cpp index 349891d04d..a77c8171a2 100644 --- a/Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/src/internal/MinimalView.cpp +++ b/Examples/Plugins/org.mitk.example.gui.extensionpointdefinition/src/internal/MinimalView.cpp @@ -1,65 +1,69 @@ /*=================================================================== The Medical Imaging Interaction Toolkit (MITK) Copyright (c) German Cancer Research Center, Division of Medical and Biological Informatics. All rights reserved. This software is distributed WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See LICENSE.txt or http://www.mitk.org for details. ===================================================================*/ #include "MinimalView.h" #include "org_mitk_example_gui_extensionpointdefinition_Activator.h" #include const std::string MinimalView::VIEW_ID = "org.mitk.views.minimalview"; MinimalView::MinimalView() : m_Parent(0) { } void MinimalView::CreateQtPartControl(QWidget *parent) { // create GUI widgets m_Parent = parent; m_Controls.setupUi(parent); QVBoxLayout* layout = new QVBoxLayout(m_Controls.m_ButtonContainer); + //! [Collect extensions through registry] QList changeTexts = m_Registry.GetChangeTexts(); foreach(const ChangeTextDescriptor::Pointer& changeText, changeTexts) { // Create a push button for each "changetext" descriptor QPushButton* button = new QPushButton(changeText->GetName(), m_Controls.m_ButtonContainer); button->setToolTip(changeText->GetDescription()); button->setObjectName(changeText->GetID()); layout->addWidget(button); connect(button, SIGNAL(clicked()), &m_SignalMapper, SLOT(map())); m_SignalMapper.setMapping(button, changeText->GetID()); } layout->addStretch(); connect(&m_SignalMapper, SIGNAL(mapped(QString)), this, SLOT(ChangeText(QString))); + //! [Collect extensions through registry] } void MinimalView::SetFocus () { m_Controls.m_InputText->setFocus(); } +//! [Use extended functionality to alter input text] void MinimalView::ChangeText(const QString& id) { ChangeTextDescriptor::Pointer changeTextDescr = m_Registry.Find(id); // lazily create an instance of IChangeText (the descriptor will cache it) IChangeText::Pointer changeText = changeTextDescr->CreateChangeText(); m_Controls.m_OutputText->setText(changeText->ChangeText(m_Controls.m_InputText->text())); } +//! [Use extended functionality to alter input text] diff --git a/Examples/Plugins/org.mitk.example.gui.selectionserviceqt/documentation/doxygen/SelectionServiceQt.dox b/Examples/Plugins/org.mitk.example.gui.selectionserviceqt/documentation/doxygen/SelectionServiceQt.dox index 57f0708d0c..b917f2ccbe 100644 --- a/Examples/Plugins/org.mitk.example.gui.selectionserviceqt/documentation/doxygen/SelectionServiceQt.dox +++ b/Examples/Plugins/org.mitk.example.gui.selectionserviceqt/documentation/doxygen/SelectionServiceQt.dox @@ -1,47 +1,47 @@ /** \page BlueBerryExampleSelectionServiceQt Qt Model/View selections \brief An example application plug-in with a minimal selection service based on Qt selection models. \image html SelectionServiceQT.png - In this examples the selection service is used to connect the selection of the radio buttons from one + In this example the selection service is used to connect the selection of the radio buttons from one view with the selection of the list of the other view. The SelectionView holds a QListWidget that provides the user selection (qt selection provider) for the selection listener (ListenerView). The radio buttons of the listener view are changed according to the selection in the QListWidget. Vice versa the radio buttons (the selection listener) does not provide any selection events. If the user changes the radio button state the QListWidget is not altered. For additional informations on the selection service concept see http://www.mitk.org/wiki/Article_Using_the_Selection_Service The berry::QtSelectionProvider class implements the interface berry::ISelectionProvider. Due to the model/view concept in Qt, the workbench provides the berry::QtSelectionProvider class for Qt viewers which must be provided with a QItemSelectionModel. In the SelectionView.h we declare a pointer that holds the selection provider... \snippet SelectionView.h Qt Selection Provider ...and in the SelectionView.cpp we set the selection model to the model of the QListWidget (m_SelectionList) \snippet SelectionView.cpp Qt Selection Provider registration Now that the QListWidget of the SelectionView sends out selection events we need a listener implementation. In the ListenerView.h we need to include the ISelectionListener which is a simple class with just one method. The method that implements the selection listener functionality of ISelectionListener and the pointer that holds the selection listener is declared... \snippet ListenerView.h Qt Selection Listener method and pointer ...and implemented in the cpp-file: \snippet ListenerView.cpp Qt Selection Listener method implementation Now the name of the selected list element is passed to a method that toggles the radio buttons of the ListenerView accordingly. View complete source files: \li \github{Examples/Plugins/org.mitk.example.gui.selectionserviceqt/src/internal/SelectionView.cpp,SelectionView.cpp} \li \github{Examples/Plugins/org.mitk.example.gui.selectionserviceqt/src/internal/SelectionView.h,SelectionView.h} \li \github{Examples/Plugins/org.mitk.example.gui.selectionserviceqt/src/internal/ListenerView.cpp,ListenerView.cpp} \li \github{Examples/Plugins/org.mitk.example.gui.selectionserviceqt/src/internal/ListenerView.h,ListenerView.h} -[\ref BlueBerrySelectionServiceIntro] [Next: \ref BlueBerryExampleSelectionServiceMitk] +[\ref BlueBerrySelectionServiceIntro] [Next: \ref BlueBerryExampleSelectionServiceMitk] [\ref BlueBerryExamples] */