[Gnash-commit] gnash ChangeLog server/dlist.h server/sprite_in...

[Zou Lunkai]

CVSROOT:        /sources/gnash
Module name:    gnash
Changes by:     Zou Lunkai <zoulunkai>  08/05/04 09:07:09

Modified files:
        .              : ChangeLog 
        server         : dlist.h sprite_instance.h 

Log message:
        docs.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/gnash/ChangeLog?cvsroot=gnash&r1=1.6487&r2=1.6488
http://cvs.savannah.gnu.org/viewcvs/gnash/server/dlist.h?cvsroot=gnash&r1=1.69&r2=1.70
http://cvs.savannah.gnu.org/viewcvs/gnash/server/sprite_instance.h?cvsroot=gnash&r1=1.191&r2=1.192

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/gnash/gnash/ChangeLog,v
retrieving revision 1.6487
retrieving revision 1.6488
diff -u -b -r1.6487 -r1.6488
--- ChangeLog   3 May 2008 21:08:47 -0000       1.6487
+++ ChangeLog   4 May 2008 09:07:08 -0000       1.6488
@@ -1,3 +1,7 @@
+2008-05-04 Zou Lunkai <address@hidden>
+
+       * server/sprite_instance.h, server/dlist.h: docs.
+
 2008-05-03 Sandro Santilli <address@hidden>
 
        * server/character.cpp: use namespace std, so isfinite works
@@ -168,6 +172,7 @@
          own file and document it, fix the execute
          signature to match the one expected by ControlTag.
 
+>>>>>>> 1.6487
 2008-04-30 Sandro Santilli <address@hidden>
 
        * macros/boost.m4: filesystem/exception.hpp might also

Index: server/dlist.h
===================================================================
RCS file: /sources/gnash/gnash/server/dlist.h,v
retrieving revision 1.69
retrieving revision 1.70
diff -u -b -r1.69 -r1.70
--- server/dlist.h      30 Apr 2008 02:33:06 -0000      1.69
+++ server/dlist.h      4 May 2008 09:07:09 -0000       1.70
@@ -87,8 +87,8 @@
        friend std::ostream& operator<< (std::ostream&, const DisplayList&);
 
        /// \brief
-       /// Place a new character at the specified depth depth,
-       /// replacing any other char at the same depth.
+       /// Place a new character at the specified depth,
+       /// replacing any existing character at the same depth.
        //
        /// If a character is replaced, it's unload() method
        /// is invoked.
@@ -98,15 +98,13 @@
        /// is called as last step of addition. 
        ///
        /// @param ch 
-       ///     the character to be added into the list
+       ///     the new character to be added into the list.
        ///
        /// @param depth 
-       ///     depth to be assign to the character
-       ///     using character::set_depth
+       ///     depth at which the new character is placed.
        ///
        void    place_character(character* ch, int depth);
 
-
        /// \brief
        /// Replace the old character at the specified depth with
        /// the given new character.
@@ -164,11 +162,18 @@
        ///
        /// @param color_xform
        ///     The color tranform to assign to the character at the given 
depth.
-       ///     If NULL the default color transform will be kept.
+       ///     If NULL the orignial color transform will be kept.
        //
        /// @param mat
        ///     The matrix tranform to assign to the character at the given 
depth.
-       ///     If NULL the default matrix will be kept.
+       ///     If NULL the orignial matrix will be kept.
+       ///
+       /// @param ratio
+       /// The new ratio value to assign to the character at the given depth.
+       /// If NULL the original ratio will be kept.
+       ///
+       /// @clip_depth
+       /// Not used at the moment.
        ///
        void    move_character(
                int depth,

Index: server/sprite_instance.h
===================================================================
RCS file: /sources/gnash/gnash/server/sprite_instance.h,v
retrieving revision 1.191
retrieving revision 1.192
diff -u -b -r1.191 -r1.192
--- server/sprite_instance.h    2 May 2008 17:11:56 -0000       1.191
+++ server/sprite_instance.h    4 May 2008 09:07:09 -0000       1.192
@@ -337,34 +337,44 @@
        boost::intrusive_ptr<character> add_textfield(const std::string& name,
                        int depth, float x, float y, float width, float height);
 
-       /// Place a character or mask to the DisplayList (make a timeline 
instance) 
+       /// Place a character or mask to the DisplayList.
        //
-       /// This method instantiates the given character definition 
(character_id)
-       /// and places it on the stage at the given depth using the specified
-       /// parameters for name, position, color, ratio(?) and clipping depth 
(if any).
-       ///
-       /// If the specified depth is already occupied by an instance of the 
same
-       /// character (character_id), the existing instance will be transformed 
using
-       /// move_display_object() instead.
-       ///
-       /// If the specified depth is already occupied by an instance of a 
different
-       /// character (including any dynamically-created instance), the 
behaviour is
-       /// controlled by the is_jumping_back flag. If false, this
-       /// call will result in a no-op. If true, the previously existing 
character
-       /// will be replaced by the new one, with unload() method invoked on the
-       /// removed character. 
+       /// This method instantiates the given character definition
+       /// and places it on the stage at the given depth.
        ///
-       /// Any successful new placement triggers invokation of the newly 
created
-       /// instance's LOAD event.
+       /// If the specified depth is already occupied, it results a no-ops.
+       /// Otherwise, a new character will be created and onload handler will 
be triggerred.
+       ///
+       /// @param tag
+       /// A swf defined placement tag(PlaceObject, or PlaceObject2, or 
PlaceObject3)
+       /// No ownership transfer, the tag is still owned by the 
movie_definition class.
+       ///
+       /// @return
+       ///     A pointer to the character being added or NULL
        ///
        character* add_display_object(const SWF::PlaceObject2Tag* tag, 
DisplayList& dlist);
-       // Proxy of DisplayList::move_character()
+       /// Proxy of DisplayList::move_character()
        void move_display_object(const SWF::PlaceObject2Tag* tag, DisplayList& 
dlist);
-       // Proxy of DisplayList::replace_character()
+       /// Proxy of DisplayList::replace_character()
        void replace_display_object(const SWF::PlaceObject2Tag* tag, 
DisplayList& dlist);
-       // Proxy of DisplayList::remove_character()
+       /// Proxy of DisplayList::remove_character()
        void remove_display_object(const SWF::PlaceObject2Tag* tag, 
DisplayList& dlist);
-
+       /// Proxy of DisplayList::remove_character()
+       ///
+       /// @param ch
+       /// new character to be used for replacing.
+       ///
+       /// @param depth
+       /// depth at which the old character is to be replaced.
+       ///
+       /// @use_old_cxform
+       /// if true, the cxform of the new character will be set to the old one.
+       /// if false, the cxform the new character will be untouched.
+       ///
+       /// @use_old_matrix
+       /// if true, the transformation matrix of the old character will be set 
to the old one.
+       /// if false, the transformation matrix of the old character will be 
untouched.
+       ///
        void replace_display_object(character* ch,      int depth,
                bool use_old_cxform,
                bool use_old_matrix);
@@ -373,8 +383,12 @@
        /// \brief
        /// Remove the object at the specified depth.
        //
-       /// NOTE: the id parameter is unused, but currently
-       /// required to avoid break of inheritance from movie.h
+       /// NOTE: 
+       /// (1)the id parameter is currently unused, but 
+       /// required to avoid breaking of inheritance from movie.h.
+       /// (2)the id might be used for specifying a character
+       /// in the depth(think about multiple characters within the same
+       /// depth, not tested and a rare case)
        ///
        void    remove_display_object(int depth, int /* id */)
        {