X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/5b222f1c9e0acb63c781675555c76f6129316eb1..097119648b492237f16acdf484eff8900c7c94d2:/docs/latex/wx/scpdptr.tex

diff --git a/docs/latex/wx/scpdptr.tex b/docs/latex/wx/scpdptr.tex
index f5ae98c0c4..1a5b04bc25 100644
--- a/docs/latex/wx/scpdptr.tex
+++ b/docs/latex/wx/scpdptr.tex
@@ -1,12 +1,18 @@
-\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 
+Below is an example of using a wxWidgets scoped smart pointer and 
 pointer array.
 
 \begin{verbatim}
@@ -41,19 +47,37 @@ 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>
@@ -64,22 +88,40 @@ legal name.
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
-\membersection{wxScopedPtr::wxScopedPtr}
+\membersection{wxScopedPtr::wxScopedPtr}\label{wxscopedptrctor}
 
-\func{}{wxScopedPtr}{\param{type}{ * T = NULL}}
+\func{}{explicit wxScopedPtr}{\param{type}{ * T = NULL}}
 
-Creates the smart pointer with the given pointer or none if NULL.  On
+Creates the smart pointer with the given pointer or none if {\tt NULL}.  On
 compilers that support it, this uses the explicit keyword.
 
-\membersection{wxScopedPtr::reset}
+
+\membersection{wxScopedPtr::\destruct{wxScopedPtr}}\label{wxscopedptrdtor}
+
+\func{}{\destruct{wxScopedPtr}}{\void}
+
+Destructor frees the pointer help by this object if it is not {\tt NULL}.
+
+
+\membersection{wxScopedPtr::release}\label{wxscopedptrrelease}
+
+\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}\label{wxscopedptrreset}
 
 \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.
 
-\membersection{wxScopedPtr::operator *}
+
+\membersection{wxScopedPtr::operator *}\label{wxscopedptrptr}
 
 \func{const T\&}{operator *}{\void}
 
@@ -87,24 +129,74 @@ 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 -\>}
 
-\func{const T*}{operator -\>}{\void}
+\membersection{wxScopedPtr::operator -$>$}\label{wxscopedptrref}
+
+\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.
 
-\membersection{wxScopedPtr::get}
+
+\membersection{wxScopedPtr::get}\label{wxscopedptrget}
 
 \func{const T*}{get}{\void}
 
 This operator gets the pointer stored in the smart pointer or returns NULL if
 there is none.
 
-\membersection{wxScopedPtr::swap}
 
-\func{\void}{swap}{\param{wxScopedPtr}{ \& ot}}
+\membersection{wxScopedPtr::swap}\label{wxscopedptrswap}
+
+\func{\void}{swap}{\param{wxScopedPtr}{ \& other}}
+
+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).
+
+
+
+
+%%%%%%% wxScopedTiedPtr %%%%%%%
+\section{\class{wxScopedTiedPtr}}\label{wxscopedtiedptr}
+
+This is a variation on the topic of \helpref{wxScopedPtr}{wxscopedptr}. This
+class is also a smart pointer but in addition it ``ties'' the pointer value to
+another variable. In other words, during the life time of this class the value
+of that variable is set to be the same as the value of the pointer itself and
+it is reset to its old value when the object is destroyed. This class is
+especially useful when converting the existing code (which may already store
+the pointers value in some variable) to the smart pointers.
+
+\wxheading{Example}
+
+\wxheading{Derives from}
+
+\helpref{wxScopedPtr}{wxscopedptr}
+
+\wxheading{Include files}
+
+<wx/ptr\_scpd.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxScopedTiedPtr::wxScopedTiedPtr}\label{wxscopedtiedptrctor}
+
+\func{}{wxScopedTiedPtr}{\param{T **}{ppTie}, \param{T *}{ptr}}
+
+Constructor creates a smart pointer initialized with \arg{ptr} and stores 
+\arg{ptr} in the location specified by \arg{ppTie} which must not be 
+{\tt NULL}.
+
+\membersection{wxScopedTiedPtr::\destruct{wxScopedTiedPtr}}\label{wxscopedtiedptrdtor}
+
+\func{}{\destruct{wxScopedTiedPtr}}{\void}
+
+Destructor frees the pointer help by this object and restores the value stored
+at the tied location (as specified in the \helpref{constructor}{wxscopedtiedptrctor})
+to the old value.
+
+Warning: this location may now contain an uninitialized value if it hadn't been
+initialized previously, in particular don't count on it magically being 
+{\tt NULL}!
 
-Swap the pointer inside the smart pointer with 'ot'. The pointer being swapped
-must be of the same type (hence the same class name).