added and documented wxDEFINE_SCOPED_PTR_TYPE; improved docs a bit

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@23604 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/docs/latex/wx/scpdptr.tex b/docs/latex/wx/scpdptr.tex
index 31a30569983fa7972dee6fb5dd4231e382f3336a..fe3d8cebafbba586c30519b543ded0c66372feb3 100644 (file)
--- a/docs/latex/wx/scpdptr.tex
+++ b/docs/latex/wx/scpdptr.tex
@@ -1,9 +1,15 @@
 \section{\class{wxScopedPtr}}\label{wxscopedptr}
 
 This is a simple scoped smart pointer implementation that is similar to 
 \section{\class{wxScopedPtr}}\label{wxscopedptr}
 
 This is a simple scoped smart pointer implementation that is similar to 

-the \urlref{Boost}{http://www.boost.org} smart pointers but rewritten to
+the \urlref{Boost}{http://www.boost.org/} smart pointers but rewritten to

 use macros instead.
 
 use macros instead.
 

+A smart pointer holds a pointer to an object. The memory used by the object is
+deleted when the smart pointer goes out of scope. This class is different from
+the \texttt{std::auto\_ptr<>} in so far as it doesn't provide copy constructor
+nor assignment operator. This limits what you can do with it but is much less
+surprizing than the ``destructive copy'' behaviour of the standard class.
+

 \wxheading{Example}
 
 Below is an example of using a wxWindows scoped smart pointer and 
 \wxheading{Example}
 
 Below is an example of using a wxWindows scoped smart pointer and 


@@ -41,19 +47,33 @@ pointer array.
 
 \wxheading{Declaring new smart pointer types}
 
 
 \wxheading{Declaring new smart pointer types}
 

+To declare the smart pointer class \texttt{CLASSNAME} containing pointes to a
+(possibly incomplete) type \texttt{TYPE} you should use

 \begin{verbatim}
 \begin{verbatim}

-    wxDECLAR_SCOPED_PTR( TYPE,     // type of the values
+    wxDECLARE_SCOPED_PTR( TYPE,     // type of the values

                                 CLASSNAME ); // name of the class
 \end{verbatim}
 
                                 CLASSNAME ); // name of the class
 \end{verbatim}
 

-A smart pointer holds a pointer to an object (which must be complete
-when wxDEFINE\_SCOPED\_PTR() is called). The memory used by the object is
-deleted when the smart pointer goes out of scope. The first argument
-of the macro is the pointer type, the second is the name of the new
-smart pointer class being created.  Below we will use wxScopedPtr to
+And later, when \texttt{TYPE} is fully defined, you must also use
+\begin{verbatim}
+    wxDEFINE_SCOPED_PTR( TYPE, CLASSNAME );
+\end{verbatim}
+to implement the scoped pointer class.
+
+The first argument of these macro is the pointer type, the second is the name
+of the new smart pointer class being created.  Below we will use wxScopedPtr to

 represent the scoped pointer class, but the user may create the class with any
 legal name.
 
 represent the scoped pointer class, but the user may create the class with any
 legal name.
 

+Alternatively, if you don't have to separate the point of declaration and
+definition of this class and if you accept the standard naming convention, that
+is that the scoped pointer for the class \texttt{Foo} is called 
+\texttt{FooPtr}, you can use a single macro which replaces two macros above:
+\begin{verbatim}
+    wxDEFINE_SCOPED_PTR_TYPE( TYPE );
+\end{verbatim}
+Once again, in this cass \texttt{CLASSNAME} will be \texttt{TYPEPtr}.
+

 \wxheading{Include files}
 
 <wx/ptr\_scpd.h>
 \wxheading{Include files}
 
 <wx/ptr\_scpd.h>

diff --git a/include/wx/ptr_scpd.h b/include/wx/ptr_scpd.h
index 84b3da0f84400b6d5464ed653360bab6e4810066..ff287cfad48d64845a6d58def84fd408e62d4baa 100644 (file)
--- a/include/wx/ptr_scpd.h
+++ b/include/wx/ptr_scpd.h
@@ -126,6 +126,14 @@ name::~name()                       \
     wxCHECKED_DELETE(m_ptr);        \
 }
 
     wxCHECKED_DELETE(m_ptr);        \
 }
 

+// this macro can be used for the most common case when you want to declare and
+// define the scoped pointer at the same time and want to use the standard
+// naming convention: auto pointer to Foo is called FooPtr
+#define wxDEFINE_SCOPED_PTR_TYPE(T)                                           \
+    wxDECLARE_SCOPED_PTR(T, T ## Ptr);                                        \
+    wxDEFINE_SCOPED_PTR(T, T ## Ptr)
+
+// the same but for arrays instead of simple pointers

 #define wxDECLARE_SCOPED_ARRAY(T, name)\
 class name                          \
 {                                   \
 #define wxDECLARE_SCOPED_ARRAY(T, name)\
 class name                          \
 {                                   \


@@ -174,4 +182,5 @@ void name::reset(T * p){                \
     }                                   \
 }
 
     }                                   \
 }
 

-#endif
+#endif // __WX_SCOPED_POINTER__
+