Index: code/branches/MouseAPI_FS19/src/modules/CMakeLists.txt
===================================================================
--- code/branches/MouseAPI_FS19/src/modules/CMakeLists.txt	(revision 12348)
+++ code/branches/MouseAPI_FS19/src/modules/CMakeLists.txt	(revision 12352)
@@ -54,2 +54,3 @@
 ADD_SUBDIRECTORY(wagnis)
 ADD_SUBDIRECTORY(MouseAPI)
+ADD_SUBDIRECTORY(MouseAPIExample)
Index: code/branches/MouseAPI_FS19/src/modules/MouseAPI/CMakeLists.txt
===================================================================
--- code/branches/MouseAPI_FS19/src/modules/MouseAPI/CMakeLists.txt	(revision 12348)
+++ code/branches/MouseAPI_FS19/src/modules/MouseAPI/CMakeLists.txt	(revision 12352)
@@ -1,5 +1,4 @@
 SET_SOURCE_FILES(MOUSEAPI_SRC_FILES
   mouseapi.cc
-  mouseapiexample.cc
   mousegametype.cc
   mouseapicursor.cc
Index: code/branches/MouseAPI_FS19/src/modules/MouseAPI/mouseapi.cc
===================================================================
--- code/branches/MouseAPI_FS19/src/modules/MouseAPI/mouseapi.cc	(revision 12348)
+++ code/branches/MouseAPI_FS19/src/modules/MouseAPI/mouseapi.cc	(revision 12352)
@@ -104,7 +104,7 @@
 }
 
-ClickableObjectID MouseAPI::addClickableObject(const Vector3& position, float radius, const std::list<MouseButtonCode::ByEnum>& buttons, std::function<void(MouseButtonCode::ByEnum)> onClickedFunction)
-{
-    ClickableObjectID id = !clickEvents.empty() ? clickEvents.back().id + 1:0;
+ClickableElementID MouseAPI::addClickableElement(const Vector3& position, float radius, const std::list<MouseButtonCode::ByEnum>& buttons, std::function<void(MouseButtonCode::ByEnum)> onClickedFunction)
+{
+    ClickableElementID id = !clickEvents.empty() ? clickEvents.back().id + 1:0;
     clickEvents.insert(clickEvents.end(),{id,position,radius,buttons,onClickedFunction});
     return id;
@@ -124,5 +124,5 @@
 
 
-bool MouseAPI::changePositionOfClickableObject(ClickableObjectID id,const Vector3& position)
+bool MouseAPI::changePositionOfClickableElement(ClickableElementID id,const Vector3& position)
 {
     for(auto event:clickEvents)
@@ -148,5 +148,5 @@
     return false;
 }
-bool MouseAPI::changeRadiusOfClickableObject(ClickableObjectID id,float radius)
+bool MouseAPI::changeRadiusOfClickableElement(ClickableElementID id,float radius)
 {
     for(auto event = clickEvents.begin();event != clickEvents.end();event++ )
@@ -172,5 +172,5 @@
     return false;
 }
-bool MouseAPI::deleteClickableObject(ClickableObjectID id)
+bool MouseAPI::deleteClickableElement(ClickableElementID id)
 {
     for(auto eventIt = clickEvents.begin();eventIt != clickEvents.end();eventIt++ )
@@ -197,5 +197,5 @@
 }
 
-float MouseAPI::getRadiusClick(ClickableObjectID id)
+float MouseAPI::getRadiusClick(ClickableElementID id)
 {
      for(auto eventIt = clickEvents.begin();eventIt != clickEvents.end();eventIt++ )
Index: code/branches/MouseAPI_FS19/src/modules/MouseAPI/mouseapi.h
===================================================================
--- code/branches/MouseAPI_FS19/src/modules/MouseAPI/mouseapi.h	(revision 12348)
+++ code/branches/MouseAPI_FS19/src/modules/MouseAPI/mouseapi.h	(revision 12352)
@@ -20,5 +20,5 @@
 #include "tools/interfaces/Tickable.h"
 
-/* This class implements a basic mouse-api
+/* this class implements a basic mouse-api
  * supported are mouse-clicks (left, right, mousewheel, ...) and scrolling
  *
@@ -30,11 +30,14 @@
  *
  * in short the class works by storing every element that can be clicked / scrolled on in a list
- * everytime a button is clicked or the mousewheel is turned, the list gets traversed and every element checked wheter it is clicked / scrolled on
- * checking happens by casting a ray from the camera through the mouse-cursor and testing wheter it intersects the sphere of the element
+ * everytime a button is clicked or the mousewheel is turned, the list gets traversed and every element checked if it is clicked / scrolled on
+ * checking happens by casting a ray from the camera through the mouse-cursor and testing if it intersects the sphere of the element
+ *
+ * to make it work, one has to add mouseapi in LINK_LIBRARIES in the file CMakeLists.txt of the level
+ * see CMakeLists.txt in MouseAPIExample
  */
 
 namespace orxonox
 {
-typedef uint ClickableObjectID;
+typedef uint ClickableElementID;
 typedef uint ScrollableElementID;
 
@@ -47,10 +50,10 @@
     struct clickableElement
     {
-        ClickableObjectID id;
+        ClickableElementID id;
         Vector3 position;
         float radius;
         std::list<MouseButtonCode::ByEnum> buttons;
         std::function<void(MouseButtonCode::ByEnum button)> onClickedFunction;
-        clickableElement(ClickableObjectID id,const Vector3& position,float radius,const std::list<MouseButtonCode::ByEnum>& buttons,std::function<void(MouseButtonCode::ByEnum button)> onClickedFunction):id(id),position(position),
+        clickableElement(ClickableElementID id,const Vector3& position,float radius,const std::list<MouseButtonCode::ByEnum>& buttons,std::function<void(MouseButtonCode::ByEnum button)> onClickedFunction):id(id),position(position),
             radius(radius), buttons(buttons), onClickedFunction(onClickedFunction){}
     };
@@ -58,6 +61,6 @@
     /* Elements that can be "scrolled on" are stored as scrollElement
      * there are 2 diffrent types, hence the overloaded constructor:
-     *      1) the function is called whenever one scrolls, independet from position of object and cursor
-     *      2) the function is only called when the cursor is over the object (same as with a clickElement)
+     *      1) the function is called whenever one scrolls, independet from position of element and cursor
+     *      2) the function is only called when the cursor is placed over the element (identical to the clickableElement)
      */
     struct scrollElement
@@ -127,35 +130,114 @@
      * Arguments:
      *      position: the point that needs to be clicked
-     *      radius: radius of the sphere around the position, if the cursor is inside this radius, the function will be executed (because clicking on a single point is pretty hard)
+     *      radius: radius of the sphere around the position; if the cursor is inside this radius, the function will be executed (because clicking on a single point is pretty hard)
      *      buttons: the function will only be called, if one of these buttons is pressed
      *      onClickedFunction: the function that will be called
-     *
-     */
-    ClickableObjectID addClickableObject(const Vector3& position,float radius,const std::list<MouseButtonCode::ByEnum>& buttons,std::function<void(MouseButtonCode::ByEnum button)>  onClickedFunction);
-
-    /*
-     *
+     */
+    ClickableElementID addClickableElement(const Vector3& position,float radius,const std::list<MouseButtonCode::ByEnum>& buttons,std::function<void(MouseButtonCode::ByEnum button)>  onClickedFunction);
+
+    /* add a scrollElement to the list
+     * see mouseapiexample for an example-implementation
+     * Arguments:
+     *      position: the point the cursor needs to be over
+     *      radius: radius of the sphere around the position; if the cursor is inside this radius, the function will be executed
+     *      onScrolledFunction: the function that will be called
      */
     ScrollableElementID addScrollElement(const Vector3& position,float radius,std::function<void(int abs,int rel,const IntVector2& mousePos)> onScrolledFunction);
 
-    /*
-     *
+    /* add a scrollElement to the list
+     * Arguments:
+     *      onScrolledFunction: the function that will be called, no matter where the cursor is
      */
     ScrollableElementID addScrollElement(std::function<void(int abs,int rel,const IntVector2& mousePos)> onScrolledFunction);
 
-    //true: success; false: element not found
-    bool changePositionOfClickableObject(ClickableObjectID id,const Vector3& position);
+    /* change the position of a clickableElement
+     * Arguments:
+     *      id: the ClickableElementID of the element
+     *      position: the new position of the element
+     * Return:
+     *      true if successfull
+     *      false if not successfull
+     */
+    bool changePositionOfClickableElement(ClickableElementID id,const Vector3& position);
+
+    /* change the position of a scrollElement
+     * Arguments:
+     *      id: the ScrollableElementID of the element
+     *      position: the new position of the element
+     * Return:
+     *      true if successfull
+     *      false if not successfull
+     */
     bool changePositionOfScrollableElement(ScrollableElementID id,const Vector3& position);
-    bool changeRadiusOfClickableObject(ClickableObjectID id,float radius);
+
+    /* change the radius of a clickableElement
+     * Arguments:
+     *      id: the ClickableElementID of the element
+     *      radius: the new radius of the element
+     * Return:
+     *      true if successfull
+     *      false if not successfull
+     */
+    bool changeRadiusOfClickableElement(ClickableElementID id,float radius);
+
+    /* change the radius of a scrollElement
+     * Arguments:
+     *      id: the ScrollableElementID of the element
+     *      radius: the new radius of the element
+     * Return:
+     *      true if successfull
+     *      false if not successfull
+     */
     bool changeRadiusOfScrollableElement(ScrollableElementID id,float radius);
-    bool deleteClickableObject(ClickableObjectID id);
+
+    /* remove a clickableElement
+     * Arguments:
+     *      id: the ClickableElementID of the element
+     * Return:
+     *      true if successfull
+     *      false if not successfull
+     */
+    bool deleteClickableElement(ClickableElementID id);
+
+    /* remove a scrollElement
+     * Arguments:
+     *      id: the ScrollableElementID of the element
+     * Return:
+     *      true if successfull
+     *      false if not successfull
+     */
     bool deleteScrollableElement(ScrollableElementID id);
 
-    float getRadiusClick(ClickableObjectID id);
+    /* get the current radius of a clickableElement
+     * Arguments:
+     *      id: the ClickableElementID of the element
+     */
+    float getRadiusClick(ClickableElementID id);
+
+    /* get the current radius of a scrollElement
+     * Arguments:
+     *      id: the ScrollableElementID of the element
+     */
     float getRadiusScroll(ScrollableElementID id);
+
+    /* get the current relative Position of the cursor
+     * returns a value between 0 and 1 for both x and y component
+     * (0,0) top left corner, (1,1) bottom right corner
+     */
     Vector2 getMousePosition();
 
+    /* activate the MouseAPI
+     * has to be called after the level has been created (i.e. inside the xml-port
+     * can be called multiple times, since the function checks the status of MouseAPI and does nothing if it already is active
+     */
     void activate();
+
+    // returns true if MouseAPI is active, false otherwise
     static bool isActive(){return singletonPtr_s != nullptr && getInstance().active;}
+
+    /* deactivate the MouseAPI
+     * has to be called, when the level gets closed (i.e. inside the level-destructor)
+     * the function does nothing if MouseAPI is not active
+     */
     void deactivate();
 };
Index: code/branches/MouseAPI_FS19/src/modules/MouseAPIExample/CMakeLists.txt
===================================================================
--- code/branches/MouseAPI_FS19/src/modules/MouseAPIExample/CMakeLists.txt	(revision 12352)
+++ code/branches/MouseAPI_FS19/src/modules/MouseAPIExample/CMakeLists.txt	(revision 12352)
@@ -0,0 +1,14 @@
+SET_SOURCE_FILES(MOUSEAPIEXAMPLE_SRC_FILES
+  mouseapiexample.cc
+)
+
+
+ORXONOX_ADD_LIBRARY(mouseapitest
+  MODULE
+  FIND_HEADER_FILES
+  PCH_FILE
+  LINK_LIBRARIES
+    orxonox
+    mouseapi
+  SOURCE_FILES ${MOUSEAPIEXAMPLE_SRC_FILES}
+)
Index: code/branches/MouseAPI_FS19/src/modules/MouseAPIExample/mouseapiexample.cc
===================================================================
--- code/branches/MouseAPI_FS19/src/modules/MouseAPIExample/mouseapiexample.cc	(revision 12352)
+++ code/branches/MouseAPI_FS19/src/modules/MouseAPIExample/mouseapiexample.cc	(revision 12352)
@@ -0,0 +1,106 @@
+#include "mouseapiexample.h"
+
+namespace orxonox
+{
+
+RegisterClass(MouseAPIExample);
+
+MouseAPIExample::MouseAPIExample(Context* context) : ControllableEntity(context)
+{
+    RegisterObject(MouseAPIExample);
+}
+
+MouseAPIExample::~MouseAPIExample()
+{
+    if(MouseAPI::isActive())
+        MouseAPI::getInstance().deactivate();
+}
+
+// change the size of the cube by a random number between 0.5 and 5 by clicking on it
+void MouseAPIExample::changesizeonclick(MouseButtonCode::ByEnum mouse)
+{
+    // generate random number between 0.5 and 5
+    float randomnumber = (rand()%10+1)/2.0;
+    // scale of the cube with this random number
+    this->setScale(randomnumber);
+    // change the radius of the clickableElement to the new size
+    MouseAPI::getInstance().changeRadiusOfClickableElement(cubeid,randomnumber*10);
+}
+
+// change the size of the sphere by scrolling on it
+void MouseAPIExample::changesizeonscroll(int abs,int rel,const IntVector2& mousePos)
+{
+    // get current radius of the sphere
+    float curRadius = MouseAPI::getInstance().getRadiusScroll(sphereid);
+    // set factor to 120% or 80% of the current size, depending on increase or decrease
+    float factor = curRadius/10*(1+rel/600.0);
+    // return if factor is outside of range [0.5,5] (limit size)
+    if(factor > 5 || factor < 0.5) return;
+    //scale the sphere with this factor and change the radius
+    this->setScale(factor);
+    MouseAPI::getInstance().changeRadiusOfScrollableElement(sphereid,factor*10);
+}
+
+// scale the z-component up / down with left-mouse / right-mouse (max. factor 2, min. factor 1)
+void MouseAPIExample::clickleft(MouseButtonCode::ByEnum mouse)
+{
+     // action after left-click
+     if (mouse == MouseButtonCode::Left)
+     {
+         Vector3 scale = this->getScale3D();
+         if (scale.z <= 2) this->setScale3D(scale.x,scale.y,scale.z+0.1);
+     }
+     // action after right-click
+     else if (mouse == MouseButtonCode::Right)
+     {
+         Vector3 scale = this->getScale3D();
+         if (scale.z > 1) this->setScale3D(scale.x,scale.y,scale.z-0.1);
+     }
+}
+
+// scale the y-component up / down with left-mouse / right-mouse (max. factor 2, min. factor 1)
+void MouseAPIExample::clickright(MouseButtonCode::ByEnum mouse)
+{
+    // action after left-click
+    if (mouse == MouseButtonCode::Left)
+    {
+        Vector3 scale = this->getScale3D();
+        if (scale.y <= 2) this->setScale3D(scale.x,scale.y+0.1,scale.z);
+    }
+    // action after right-click
+    else if (mouse == MouseButtonCode::Right)
+    {
+        Vector3 scale = this->getScale3D();
+        if (scale.y > 1) this->setScale3D(scale.x,scale.y-0.1,scale.z);
+    }
+}
+
+// standard XML-Port
+void MouseAPIExample::XMLPort(Element& xmlelement, XMLPort::Mode mode)
+{
+    SUPER(MouseAPIExample, XMLPort, xmlelement, mode);
+
+    // differentiate between several elements by an identifier "id"
+    XMLPortParam(MouseAPIExample, "id", setId, getId, xmlelement, mode);
+    if(this->getId() == 1) // id == 1; cube
+    {
+        // add the cube to the list with clickable elements, set the radius to 10, define the function changesizeonclick to be called after a left-click
+        cubeid = MouseAPI::getInstance().addClickableElement(this->getWorldPosition(),10,std::list<MouseButtonCode::ByEnum>{MouseButtonCode::Left},[this](MouseButtonCode::ByEnum mouse){this->changesizeonclick(mouse);});
+    }
+    else if(this->getId() == 2) // id == 2; sphere
+    {
+        // add the sphere to the list with scrollable Elements, set the radius to 10, define the function changesizeonscroll to be called while scrolling
+        sphereid = MouseAPI::getInstance().addScrollElement(this->getWorldPosition(), 10, [this](int abs, int rel, const IntVector2& mousePos){this->changesizeonscroll(abs,rel,mousePos);});
+    }
+    else if(this->getId() == 3) // id == 3; long block
+    {
+        // add the left and right part of the long block to the list with clickable Elements and define clickleft/clickright to be called
+        // (Position (0,70,+/-70) is hardcoded)
+        leftid = MouseAPI::getInstance().addClickableElement(Vector3(0,70,-70),20,std::list<MouseButtonCode::ByEnum>{MouseButtonCode::Left,MouseButtonCode::Right},[this](MouseButtonCode::ByEnum mouse){this->clickleft(mouse);});
+        rightid = MouseAPI::getInstance().addClickableElement(Vector3(0,70,70),20,std::list<MouseButtonCode::ByEnum>{MouseButtonCode::Left,MouseButtonCode::Right},[this](MouseButtonCode::ByEnum mouse){this->clickright(mouse);});
+    }
+
+    // activate MouseAPI
+    MouseAPI::getInstance().activate();
+}
+}
Index: code/branches/MouseAPI_FS19/src/modules/MouseAPIExample/mouseapiexample.h
===================================================================
--- code/branches/MouseAPI_FS19/src/modules/MouseAPIExample/mouseapiexample.h	(revision 12352)
+++ code/branches/MouseAPI_FS19/src/modules/MouseAPIExample/mouseapiexample.h	(revision 12352)
@@ -0,0 +1,33 @@
+#ifndef MOUSEAPIEXAMPLE_H
+#define MOUSEAPIEXAMPLE_H
+
+#include "core/XMLPort.h"
+#include "MouseAPI/mouseapi.h"
+#include "core/CoreIncludes.h"
+#include "worldentities/ControllableEntity.h"
+#include <list>
+
+namespace orxonox
+{
+class MouseAPIExample : public ControllableEntity
+{
+public:
+    MouseAPIExample(Context *context);
+    ~MouseAPIExample();
+    virtual void XMLPort(Element& xmlelement, XMLPort::Mode mode);
+    void changesizeonclick(MouseButtonCode::ByEnum mouse);
+    void changesizeonscroll(int abs,int rel,const IntVector2& mousePos);
+    void clickleft(MouseButtonCode::ByEnum mouse);
+    void clickright(MouseButtonCode::ByEnum mouse);
+    inline void setId(int id)
+        { this->id = id; }
+    inline int getId() const
+        { return this->id; }
+private:
+    int id;
+    ClickableElementID cubeid;
+    ScrollableElementID sphereid;
+    ClickableElementID leftid,rightid;
+};
+}
+#endif // MOUSEAPIEXAMPLE_H
