define _HPUX_SOURCE under HP-UX, otherwise many things are not defined in standard...

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

diff --git a/docs/latex/wx/scpdptr.tex b/docs/latex/wx/scpdptr.tex
index 844aefbe2f379cdbdc6e7a2cbdd683f45b512033..1a5b04bc25dc23968360bc2ce61cb07fdcc09812 100644 (file)
--- 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 
 
 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}
 
 \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}
 pointer array.
 
 \begin{verbatim}


@@ -41,19 +47,37 @@ 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>


@@ -64,22 +88,40 @@ legal name.
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \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.
 
 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}}
 
 
 \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.
 
 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}
 
 
 \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.
 
 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.
 
 
 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.
 
 
 \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).