added interface headers with latest discussed changes

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

interface/ptr_scpd.h

@@ -0,0 +1,243 @@
+/////////////////////////////////////////////////////////////////////////////
+// Name:        ptr_scpd.h
+// Purpose:     documentation for wxScopedPtr class
+// Author:      wxWidgets team
+// RCS-ID:      $Id$
+// Licence:     wxWindows license
+/////////////////////////////////////////////////////////////////////////////
+
+/**
+    @class wxScopedPtr
+    @wxheader{ptr_scpd.h}
+    
+    This is a simple scoped smart pointer implementation that is similar to 
+    the Boost smart pointers but rewritten to
+    use macros instead.
+    
+    Since wxWidgets 2.9.0 there is also a templated version of this class
+    with the same name. See wxScopedPtrT.
+    
+    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 @c 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.
+    
+    @library{wxbase}
+    @category{FIXME}
+    
+    @seealso
+    wxScopedArray
+*/
+class wxScopedPtr 
+{
+public:
+    /**
+        Creates the smart pointer with the given pointer or none if @NULL.  On
+        compilers that support it, this uses the explicit keyword.
+    */
+    explicit wxScopedPtr(type T = @NULL);
+
+    /**
+        Destructor frees the pointer help by this object if it is not @NULL.
+    */
+    ~wxScopedPtr();
+
+    /**
+        This operator gets the pointer stored in the smart pointer or returns @NULL if
+        there is none.
+    */
+    const T* get();
+
+    /**
+        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.
+    */
+    const T operator *();
+
+    /**
+        This operator works like the standard C++ pointer operator to return the pointer
+        in the smart pointer or @NULL if it is empty.
+    */
+    const T* operator -();
+
+    /**
+        Returns the currently hold pointer and resets the smart pointer object to 
+        @NULL. After a call to this function the caller is responsible for
+        deleting the pointer.
+    */
+    T * release();
+
+    /**
+        Deletes the currently held pointer and sets it to @e 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.
+    */
+     reset(T p  = @NULL);
+
+    /**
+        Swap the pointer inside the smart pointer with @e other. The pointer being
+        swapped must be of the same type (hence the same class name).
+    */
+     swap(wxScopedPtr amp; other);
+};
+
+
+/**
+    @class wxScopedArray
+    @wxheader{ptr_scpd.h}
+    
+    This is a simple scoped smart pointer array implementation that is similar to 
+    the Boost smart pointers but rewritten to
+    use macros instead.
+    
+    @library{wxbase}
+    @category{FIXME}
+    
+    @seealso
+    wxScopedPtr
+*/
+class wxScopedArray 
+{
+public:
+    /**
+        Creates the smart pointer with the given pointer or none if @NULL.  On
+        compilers that support it, this uses the explicit keyword.
+    */
+    wxScopedArray(type T = @NULL);
+
+    /**
+        This operator gets the pointer stored in the smart pointer or returns @NULL if
+        there is none.
+    */
+    const T* get();
+
+    /**
+        This operator acts like the standard [] indexing operator for C++ arrays.  The
+        function does not do bounds checking.
+    */
+    const T operator [](long int i);
+
+    /**
+        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.
+    */
+     reset(T p  = @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).
+    */
+     swap(wxScopedPtr amp; ot);
+};
+
+
+/**
+    @class wxScopedTiedPtr
+    @wxheader{ptr_scpd.h}
+    
+    This is a variation on the topic of 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.
+    
+    @library{wxbase}
+    @category{FIXME}
+*/
+class wxScopedTiedPtr 
+{
+public:
+    /**
+        Constructor creates a smart pointer initialized with @e ptr and stores 
+        @e ptr in the location specified by @e ppTie which must not be 
+        @NULL.
+    */
+    wxScopedTiedPtr(T ** ppTie, T * ptr);
+
+    /**
+        Destructor frees the pointer help by this object and restores the value stored
+        at the tied location (as specified in the @ref ctor() constructor)
+        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 
+        @NULL!
+    */
+    ~wxScopedTiedPtr();
+};
+
+
+/**
+    @class wxScopedPtrT
+    @wxheader{ptr_scpd.h}
+    
+    A scoped pointer template class. It is the template version of
+    the old-style @ref overview_wxscopedptr "scoped pointer macros".
+    
+    @library{wxbase}
+    @category{FIXME}
+    
+    @seealso
+    wxSharedPtr, wxWeakRef
+*/
+class wxScopedPtr<T> 
+{
+public:
+    /**
+        Constructor.
+    */
+    wxScopedPtrT(T * ptr = @NULL);
+
+    /**
+        Destructor.
+    */
+    ~wxScopedPtrT();
+
+    /**
+        Returns pointer to object or @NULL.
+    */
+    T * get();
+
+    /**
+        Conversion to a boolean expression (in a variant which is not 
+        convertable to anything but a boolean expression). If this class
+        contains a valid pointer it will return @e @true, if it contains
+        a @NULL pointer it will return @e @false.
+    */
+     operator unspecified_bool_type();
+
+    /**
+        Returns a reference to the object. If the internal pointer is @NULL
+        this method will cause an assert in debug mode.
+    */
+    T operator*();
+
+    /**
+        Returns pointer to object. If the pointer is @NULL this method will 
+        cause an assert in debug mode.
+    */
+    T * operator-();
+
+    /**
+        Releases the current pointer and returns it.
+        Afterwards the caller is responsible for deleting
+        the data contained in the scoped pointer before.
+    */
+    T* release();
+
+    /**
+        Reset pointer to the value of @e ptr. The
+        previous pointer will be deleted.
+    */
+    void reset(T * ptr = @NULL);
+
+    /**
+        Swaps pointers.
+    */
+    void swap(wxScopedPtr<T> & ot);
+};