Applied patch [ 587450 ] Scoped Smart pointers and docs

By Jesse Lovelace (thementat)


git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@16409 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/classes.tex

@@ -241,6 +241,8 @@
 \input sashlayw.tex
 \input sashwin.tex
 \input screendc.tex
+\input scpdarry.tex
+\input scpdptr.tex
 \input scrolbar.tex
 \input scrolwin.tex
 \input scrolevt.tex

docs/latex/wx/scpdarry.tex

@@ -0,0 +1,102 @@
+\section{wxScopedArray}\label{wxscopedarray}
+
+This is a simple scoped smart pointer array implementation that is similar to 
+the \urlref{Boost}{http://www.boost.org} smart pointers but rewritten to
+use macros instead.
+
+\wxheading{Example}
+
+Below is an example of using a wxWindows scoped smart pointer and 
+pointer array.
+
+\begin{verbatim}
+  class MyClass { /* ... */ };
+
+  // declare a smart pointer to a MyClass called wxMyClassPtr
+  wxDECLARE_SCOPED_PTR(MyClass, wxMyClassPtr)
+  // declare a smart pointer to an array of chars
+  wxDECLARE_SCOPED_ARRAY(char, wxCharArray)
+
+  ...
+
+  // define the first pointer class, must be complete
+  wxDEFINE_SCOPED_PTR(MyClass, wxMyClassPtr)
+  // define the second pointer class
+  wxDEFINE_SCOPED_ARRAY(char, wxCharArray)
+
+  // create an object with a new pointer to MyClass
+  wxMyClassPtr theObj(new MyClass());
+  // reset the pointer (deletes the previous one)
+  theObj.reset(new MyClass());
+
+  // access the pointer
+  theObj->MyFunc();
+
+  // create an object with a new array of chars
+  wxCharArray theCharObj(new char[100]);
+
+  // access the array
+  theCharObj[0] = "!";
+\end{verbatim}
+
+\wxheading{Declaring new smart pointer types}
+
+\begin{verbatim}
+    wxDECLAR_SCOPED_ARRAY( 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_ARRAY() 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 wxScopedArray to
+represent the scoped pointer array class, but the user may create the class 
+with any legal name.
+
+\wxheading{Include files}
+
+<wx/ptr\_scpd.h>
+
+\wxheading{See also}
+
+\helpref{wxScopedPtr}{wxscopedptr}\rtfsp
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxScopedArray::wxScopedArray}
+
+\func{}{wxScopedArray}{\param{type}{ * T = NULL}}
+
+Creates the smart pointer with the given pointer or none if NULL.  On
+compilers that support it, this uses the explicit keyword.
+
+\membersection{wxScopedArray::reset}
+
+\func{\void}{reset}{\param{T}{ p * = NULL}}
+
+Deletes the currently held pointer and sets it to '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{wxScopedArray::operator []}
+
+\func{const T \&}{operator []}{\param{long int}{i}}
+
+This operator acts like the standard [] indexing operator for C++ arrays.  The
+function does not do bounds checking.
+
+\membersection{wxScopedArray::get}
+
+\func{const T*}{get}{\void}
+
+This operator gets the pointer stored in the smart pointer or returns NULL if
+there is none.
+
+\membersection{wxScopedArray::swap}
+
+\func{\void}{swap}{\param{wxScopedPtr}{ \& ot}}
+
+Swap the pointer inside the smart pointer with 'ot'. The pointer being swapped
+must be of the same type (hence the same class name).
+

docs/latex/wx/scpdptr.tex

@@ -0,0 +1,110 @@
+\section{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
+use macros instead.
+
+\wxheading{Example}
+
+Below is an example of using a wxWindows scoped smart pointer and 
+pointer array.
+
+\begin{verbatim}
+  class MyClass { /* ... */ };
+
+  // declare a smart pointer to a MyClass called wxMyClassPtr
+  wxDECLARE_SCOPED_PTR(MyClass, wxMyClassPtr)
+  // declare a smart pointer to an array of chars
+  wxDECLARE_SCOPED_ARRAY(char, wxCharArray)
+
+  ...
+
+  // define the first pointer class, must be complete
+  wxDEFINE_SCOPED_PTR(MyClass, wxMyClassPtr)
+  // define the second pointer class
+  wxDEFINE_SCOPED_ARRAY(char, wxCharArray)
+
+  // create an object with a new pointer to MyClass
+  wxMyClassPtr theObj(new MyClass());
+  // reset the pointer (deletes the previous one)
+  theObj.reset(new MyClass());
+
+  // access the pointer
+  theObj->MyFunc();
+
+  // create an object with a new array of chars
+  wxCharArray theCharObj(new char[100]);
+
+  // access the array
+  theCharObj[0] = "!";
+\end{verbatim}
+
+\wxheading{Declaring new smart pointer types}
+
+\begin{verbatim}
+    wxDECLAR_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
+represent the scoped pointer class, but the user may create the class with any
+legal name.
+
+\wxheading{Include files}
+
+<wx/ptr\_scpd.h>
+
+\wxheading{See also}
+
+\helpref{wxScopedArray}{wxscopedarray}\rtfsp
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxScopedPtr::wxScopedPtr}
+
+\func{}{wxScopedPtr}{\param{type}{ * T = NULL}}
+
+Creates the smart pointer with the given pointer or none if NULL.  On
+compilers that support it, this uses the explicit keyword.
+
+\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 
+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 *}
+
+\func{const T\&}{operator *}{\void}
+
+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}
+
+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}
+
+\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}}
+
+Swap the pointer inside the smart pointer with 'ot'. The pointer being swapped
+must be of the same type (hence the same class name).
+