added and documented wxDEFINE_SCOPED_PTR_TYPE; improved docs a bit

[wxWidgets.git] / docs / latex / wx / scpdptr.tex

diff --git a/docs/latex/wx/scpdptr.tex b/docs/latex/wx/scpdptr.tex
index 844aefbe2f379cdbdc6e7a2cbdd683f45b512033..fe3d8cebafbba586c30519b543ded0c66372feb3 100644 (file)
--- a/docs/latex/wx/scpdptr.tex
+++ b/docs/latex/wx/scpdptr.tex
@@ -1,9 +1,15 @@
-\section{wxScopedPtr}\label{wxscopedptr}
+\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.
 
+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 
@@ -41,19 +47,33 @@ pointer array.
 
 \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}
-    wxDECLAR_SCOPED_PTR( TYPE,     // type of the values
+    wxDECLARE_SCOPED_PTR( TYPE,     // type of the values
                                 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.
 
+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>
@@ -71,11 +91,20 @@ legal name.
 Creates the smart pointer with the given pointer or none if NULL.  On
 compilers that support it, this uses the explicit keyword.
 
+\membersection{wxScopedPtr::release}
+
+\func{T *}{release}{\void}
+
+Returns the currently hold pointer and resets the smart pointer object to 
+{\tt NULL}. After a call to this function the caller is responsible for
+deleting the pointer.
+
+
 \membersection{wxScopedPtr::reset}
 
 \func{\void}{reset}{\param{T}{ p * = NULL}}
 
-Deletes the currently held pointer and sets it to 'p' or to NULL if no 
+Deletes the currently held pointer and sets it to {\it p} or to NULL if no 
 arguments are specified. This function does check to make sure that the
 pointer you are assigning is not the same pointer that is already stored.
 
@@ -87,9 +116,9 @@ This operator works like the standard C++ pointer operator to return the object
 being pointed to by the pointer.  If the pointer is NULL or invalid this will
 crash.
 
-\membersection{wxScopedPtr::operator -\>}
+\membersection{wxScopedPtr::operator -$>$} % TODO
 
-\func{const T*}{operator -\>}{\void}
+\func{const T*}{operator -$>$}{\void} % TODO
 
 This operator works like the standard C++ pointer operator to return the pointer
 in the smart pointer or NULL if it is empty.
@@ -103,8 +132,8 @@ there is none.
 
 \membersection{wxScopedPtr::swap}
 
-\func{\void}{swap}{\param{wxScopedPtr}{ \& ot}}
+\func{\void}{swap}{\param{wxScopedPtr}{ \& other}}
 
-Swap the pointer inside the smart pointer with 'ot'. The pointer being swapped
-must be of the same type (hence the same class name).
+Swap the pointer inside the smart pointer with {\it other}. The pointer being
+swapped must be of the same type (hence the same class name).