Changeset 12352 for code/branches/MouseAPI_FS19/src/modules/MouseAPI

Timestamp:

May 9, 2019, 2:05:27 PM (6 years ago)

Author:

mkarpf

Message:

separated MouseAPIExample from MouseAPI

finished comments in MouseAPI.h

Location:

code/branches/MouseAPI_FS19/src/modules/MouseAPI

Files:

• CMakeLists.txt (modified) (1 diff)
• mouseapi.cc (modified) (5 diffs)
• mouseapi.h (modified) (5 diffs)

code/branches/MouseAPI_FS19/src/modules/MouseAPI/CMakeLists.txt

@@ -1 +1 @@
 SET_SOURCE_FILES(MOUSEAPI_SRC_FILES
   mouseapi.cc
-  mouseapiexample.cc
   mousegametype.cc
   mouseapicursor.cc

code/branches/MouseAPI_FS19/src/modules/MouseAPI/mouseapi.cc

@@ -104 +104 @@
 }
 
-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 +124 @@
 
 
-bool MouseAPI::changePositionOfClickableObject(ClickableObjectID id,const Vector3& position)
+bool MouseAPI::changePositionOfClickableElement(ClickableElementID id,const Vector3& position)
 {
     for(auto event:clickEvents)
@@ -148 +148 @@
     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 +172 @@
     return false;
 }
-bool MouseAPI::deleteClickableObject(ClickableObjectID id)
+bool MouseAPI::deleteClickableElement(ClickableElementID id)
 {
     for(auto eventIt = clickEvents.begin();eventIt != clickEvents.end();eventIt++ )
@@ -197 +197 @@
 }
 
-float MouseAPI::getRadiusClick(ClickableObjectID id)
+float MouseAPI::getRadiusClick(ClickableElementID id)
 {
      for(auto eventIt = clickEvents.begin();eventIt != clickEvents.end();eventIt++ )

code/branches/MouseAPI_FS19/src/modules/MouseAPI/mouseapi.h

@@ -20 +20 @@
 #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 +30 @@
  *
  * 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 +50 @@
     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 +61 @@
     /* 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 +130 @@
      * 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();
 };