Fix #1783: repeated error message on console

[simgear.git] / simgear / canvas / CanvasEvent.hxx

diff --git a/simgear/canvas/CanvasEvent.hxx b/simgear/canvas/CanvasEvent.hxx
index 0e98c6f1e07976f54196424cc1cbd74ec5e1022d..23da1048c2ef28a1d4a876a8b6804a78a9c97ebf 100644 (file)
--- a/simgear/canvas/CanvasEvent.hxx
+++ b/simgear/canvas/CanvasEvent.hxx
@@ -1,4 +1,5 @@
-// Canvas Event for event model similar to DOM Level 3 Event Model
+/// @file
+/// Canvas Event for event model similar to DOM Level 3 Event Model
 //
 // Copyright (C) 2012  Thomas Geymayer <tomgey@gmail.com>
 //
@@ -27,26 +28,36 @@ namespace simgear
 namespace canvas
 {
 
+  /**
+   * Base class for all Canvas events.
+   *
+   * The event system is closely following the specification of the DOM Level 3
+   * Event Model.
+   */
   class Event:
     public SGReferenced
   {
     public:
 
+      /// Event type identifier
       enum Type
       {
         UNKNOWN,
-#       define ENUM_MAPPING(name, str) name,
+#       define ENUM_MAPPING(name, str, class_name)\
+                 name, /*!< class_name (type=str) */
 #         include "CanvasEventTypes.hxx"
 #       undef ENUM_MAPPING
-        CUSTOM_EVENT ///<! all user defined event types share the same id. They
-                     ///   are just differentiated by using the type string.
+        CUSTOM_EVENT ///< First event type id available for user defined event
+                     ///  type.
+                     /// @see CustomEvent
       };
 
       int               type;
       ElementWeakPtr    target,
                         current_target;
       double            time;
-      bool              propagation_stopped;
+      bool              propagation_stopped,
+                        default_prevented;
 
       Event();
 
@@ -72,10 +83,33 @@ namespace canvas
       ElementWeakPtr getTarget() const;
       ElementWeakPtr getCurrentTarget() const;
 
+      /**
+       * Get time at which the event was generated.
+       */
       double getTime() const;
 
+      /**
+       * Prevent further propagation of the event during event flow.
+       *
+       * @note This does not prevent calling further event handlers registered
+       *       on the current event target.
+       */
       void stopPropagation();
 
+      /**
+       * Cancel any default action normally taken as result of this event.
+       *
+       * @note For event handlers registered on the DesktopGroup (Nasal:
+       *       canvas.getDesktop()) this stops the event from being further
+       *       propagated to the normal FlightGear input event handling code.
+       */
+      void preventDefault();
+
+      /**
+       * Get if preventDefault() has been called.
+       */
+      bool defaultPrevented() const;
+
       static int getOrRegisterType(const std::string& type);
       static int strToType(const std::string& type);
       static std::string typeToStr(int type);