no changes, just come cleanup and more comments

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

\section{\class{wxObjectDataPtr<T>}}\label{wxobjectdataptr}

This is helper template class primarily written to avoid memory 
leaks because of missing calls to \helpref{wxObjectRefData::DecRef}{wxobjectrefdatadecref}.

Despite the name this template can actually be used as a
smart pointer for any class implementing the reference
counting interface which only consists of the two methods
{\bf T::IncRef()} and {\bf T::DecRef()}.

The difference to \helpref{wxSharedPtr}{wxsharedptr} is that
wxObjectDataPtr relies on the reference counting to be in
the class pointed to where as wxSharedPtr implements the
reference counting itself.

\wxheading{See also}

\helpref{wxObject}{wxobject},
\helpref{wxObjectRefData}{wxobjectrefdata},
\helpref{Reference counting}{trefcount}

\helpref{wxSharedPtr}{wxsharedptr}, 
\helpref{wxScopedPtr}{wxscopedptrtemplate},
\helpref{wxWeakRef}{wxweakref}


\wxheading{Derived from}

No base class

\wxheading{Include files}

<object.h>

\wxheading{Data structures}

{\small%
\begin{verbatim}
typedef T element_type
\end{verbatim}
}%

\wxheading{Example}

\begin{verbatim}

class MyCarRefData: public wxObjectRefData
{
public:
    MyCarRefData()  { m_price = 0; }
    
    MyCarRefData( const MyCarRefData& data )
        : wxObjectRefData()
    {
        m_price = data.m_price;
    }

    void SetPrice( int price )  { m_price = price; }
    int GetPrice()              { return m_price; }
    
protected:
    int m_price;
};

class MyCar
{
public:
    MyCar( int price ) : m_data( new MyCarRefData )
    {
        m_data->SetPrice( price );
    }
    
    MyCar& operator =( const MyCar& tocopy )
    {
        m_data = tocopy.m_data;
        return *this;
    }
    
    bool operator == ( const MyCar& other ) const
    {
        if (m_data.get() == other.m_data.get()) return true;
        return (m_data->GetPrice() == other.m_data->GetPrice());
    }

    void SetPrice( int price )
    {
       UnShare();
       m_data->SetPrice( price );
    }
    
    int GetPrice() const
    {
       return m_data->GetPrice();
    }

    wxObjectDataPtr<MyCarRefData> m_data;
    
protected:
    void UnShare()
    {
        if (m_data->GetRefCount() == 1)
            return;
    
        m_data.reset( new MyCarRefData( *m_data ) );
    }
};

\end{verbatim}


\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxObjectDataPtr<T>::wxObjectDataPtr<T>}\label{wxobjectdataptrwxobjectdataptr}

\func{wxEXPLICIT}{wxObjectDataPtr<T>}{\param{T* }{ptr = NULL}}

Constructor. {\it ptr} is a pointer to the reference
counted object to which this class points. If {\it ptr}
is not NULL {\bf T::IncRef()} will be called on the
object.

\func{}{wxObjectDataPtr<T>}{\param{const wxObjectDataPtr<T>\& }{tocopy}}

This copy constructor increases the count of the reference
counted object to which {\it tocopy} points and then this
class will point to, as well.

\membersection{wxObjectDataPtr<T>::\destruct{wxObjectDataPtr<T>}}\label{wxobjectdataptrdtor}

\func{}{\destruct{wxObjectDataPtr<T>}}{\void}

Decreases the reference count of the object to which this
class points.

\membersection{wxObjectDataPtr<T>::operator unspecified\_bool\_type}\label{wxobjectdataptroperatorbool}

\constfunc{}{operator unspecified\_bool\_type}{\void}

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 {\it true}, if it contains
a NULL pointer it will return {\it false}.

\membersection{wxObjectDataPtr<T>::operator*}\label{wxobjectdataptroperatorreft}

\constfunc{T \&}{operator*}{\void}

Returns a reference to the object. If the internal pointer is NULL
this method will cause an assert in debug mode.

\membersection{wxObjectDataPtr<T>::operator->}\label{wxobjectdataptroperatorpointer}

\constfunc{T*}{operator->}{\void}

Returns a pointer to the reference counted object to which
this class points. If this the internal pointer is NULL,
this method will assert in debug mode.

\membersection{wxObjectDataPtr<T>::operator=}\label{wxobjectdataptroperatorassign}

\func{wxObjectDataPtr<T>\& operator}{operator=}{\param{const wxObjectDataPtr<T>\& }{tocopy}}

\func{wxObjectDataPtr<T>\& operator}{operator=}{\param{T* }{ptr}}

Assignment operators.

\membersection{wxObjectDataPtr<T>::get}\label{wxobjectdataptrget}

\constfunc{T*}{get}{\void}

Gets a pointer to the reference counted object to which
this class points.

\membersection{wxObjectDataPtr<T>::reset}\label{wxobjectdataptrreset}

\func{void}{reset}{\param{T* }{ptr}}

Reset this class to {\it ptr} which points to a reference
counted object and calls {\bf T::DecRef()} on the previously
owned object.