[Gnash-commit] gnash ChangeLog server/movie_root.h

[Zou Lunkai]

CVSROOT:        /sources/gnash
Module name:    gnash
Changes by:     Zou Lunkai <zoulunkai>  07/06/22 02:11:06

Modified files:
        .              : ChangeLog 
        server         : movie_root.h 

Log message:
        document KeyListener class and related stuff

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/gnash/ChangeLog?cvsroot=gnash&r1=1.3596&r2=1.3597
http://cvs.savannah.gnu.org/viewcvs/gnash/server/movie_root.h?cvsroot=gnash&r1=1.59&r2=1.60

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/gnash/gnash/ChangeLog,v
retrieving revision 1.3596
retrieving revision 1.3597
diff -u -b -r1.3596 -r1.3597
--- ChangeLog   22 Jun 2007 01:16:55 -0000      1.3596
+++ ChangeLog   22 Jun 2007 02:11:05 -0000      1.3597
@@ -2,6 +2,7 @@
 
        * testsuite/actionscript.all/enumerate.as: cleanups, tests are not
          dependent on enumeration order now.
+       * server/movie_root.h: document KeyListener class and related stuff.
        
 2007-06-22 Markus Gothe <address@hidden>
 

Index: server/movie_root.h
===================================================================
RCS file: /sources/gnash/gnash/server/movie_root.h,v
retrieving revision 1.59
retrieving revision 1.60
diff -u -b -r1.59 -r1.60
--- server/movie_root.h 16 Jun 2007 11:27:40 -0000      1.59
+++ server/movie_root.h 22 Jun 2007 02:11:06 -0000      1.60
@@ -15,7 +15,7 @@
 // along with this program; if not, write to the Free Software
 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 
-/* $Id: movie_root.h,v 1.59 2007/06/16 11:27:40 strk Exp $ */
+/* $Id: movie_root.h,v 1.60 2007/06/22 02:11:06 zoulunkai Exp $ */
 
 /// \page events_handling Handling of user events
 ///
@@ -91,9 +91,10 @@
 namespace gnash
 {
 
-  #ifdef NEW_KEY_LISTENER_LIST_DESIGN
+#ifdef NEW_KEY_LISTENER_LIST_DESIGN
 class KeyListener{
        public:
+               /// all constructed key listeners are not registered to the 
global Key object by default.
                KeyListener(boost::intrusive_ptr<as_object> obj, bool 
flag=false)
                : _listener(obj), _user_defined_handler_added(flag)
                {}
@@ -103,12 +104,22 @@
                bool operator == (const KeyListener & rhs ) const { return 
_listener.get() == rhs.get(); }
                bool operator != (const KeyListener & rhs ) const { return 
_listener.get() != rhs.get(); }
 
+               /// \brief
+               /// Return true if the _listener has been registered by 
Key.addListener(),
+               /// false if the _listener has not been registered or 
unregistered by Key.removeListener().
+               /// The return value is used to decide if we should invoke the 
user defined handler.
                bool isRegistered() const { return _user_defined_handler_added; 
}
+               
+               /// unregister the key listener
                void unregisterUserHandler() { _user_defined_handler_added = 
false; }
+               
+               /// register the key listener
                void registerUserHandler() { _user_defined_handler_added = 
true; }
 
        private:
+               /// the listener object, could be a character or a general 
as_object
                boost::intrusive_ptr<as_object> _listener;
+               /// mark if the object has been registered by Key.addListener()
                bool _user_defined_handler_added;
        };
 #endif 
@@ -395,7 +406,13 @@
 
        DSOEXPORT void notify_key_listeners(key::code k, bool down);
 #ifdef NEW_KEY_LISTENER_LIST_DESIGN
+       // Push a new key listener to the container if it is not there,
+       // otherwise, just register it.
        void add_key_listener(const KeyListener& listener);
+       
+       // Unregister the specified key listener, never really remove it.
+       // The name is confusing just that the built-in Key.removeListener() 
+       // does not really remove any thing.
        void remove_key_listener(const KeyListener& listener);
 #else
        void add_key_listener(as_object* listener);
@@ -465,6 +482,9 @@
 
        /// Remove all listeners with a ref-count of 1
        /// (only referenced as key listeners)
+       // in new design:
+       // remove unloaded characters and unregistered as_objects 
+       // from the key listeners container.
        void cleanup_key_listeners();
 
        /// Return the current Stage object