-\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}
\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>
\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}
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).
projects / wxWidgets.git / blobdiff