X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/762e199741e236841278dfa6c08a7a0ca376252e..760f0fc2f4b875beb06e5ecd6d69b891d8360efe:/docs/latex/wx/scpdptr.tex diff --git a/docs/latex/wx/scpdptr.tex b/docs/latex/wx/scpdptr.tex index 3fab597dfa..1a5b04bc25 100644 --- a/docs/latex/wx/scpdptr.tex +++ b/docs/latex/wx/scpdptr.tex @@ -1,12 +1,18 @@ \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} @@ -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} + + + +\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).