add wxSYS_DCLICK_TIME system metric constant; use it for the generic list control...

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

\section{\class{wxObject}}\label{wxobject}

This is the root class of many of the wxWidgets classes.
It declares a virtual destructor which ensures that
destructors get called for all derived class objects where necessary.

wxObject is the hub of a dynamic object creation
scheme, enabling a program to create instances of a class only knowing
its string class name, and to query the class hierarchy.

The class contains optional debugging versions
of {\bf new} and {\bf delete}, which can help trace memory allocation
and deallocation problems.

wxObject can be used to implement \helpref{reference counted}{trefcount} objects,
such as wxPen, wxBitmap and others (see \helpref{this list}{refcountlist}).

\wxheading{See also}

\helpref{wxClassInfo}{wxclassinfo}, \helpref{Debugging overview}{debuggingoverview},\rtfsp
\helpref{wxObjectRefData}{wxobjectrefdata}

\wxheading{Derived from}

No base class

\wxheading{Include files}

<wx/object.h>

\wxheading{Library}

\helpref{wxBase}{librarieslist}

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

\membersection{wxObject::wxObject}\label{wxobjectctor}

\func{}{wxObject}{\void}

\func{}{wxObject}{\param{const wxObject\&}{ other}}

Default and copy constructors.

\membersection{wxObject::\destruct{wxObject}}\label{wxobjectdtor}

\func{}{wxObject}{\void}

Destructor. Performs dereferencing, for those objects
that use reference counting.

\membersection{wxObject::m\_refData}\label{wxobjectmrefdata}

\member{wxObjectRefData* }{m\_refData}

Pointer to an object which is the object's reference-counted data.

\wxheading{See also}

\helpref{wxObject::Ref}{wxobjectref}, \helpref{wxObject::UnRef}{wxobjectunref},\rtfsp
\helpref{wxObject::SetRefData}{wxobjectsetrefdata},\rtfsp
\helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp
\helpref{wxObjectRefData}{wxobjectrefdata}

\membersection{wxObject::Dump}\label{wxobjectdump}

\func{void}{Dump}{\param{ostream\&}{ stream}}

A virtual function that may be redefined by derived classes to allow dumping of
memory states.

This function is only defined in debug build and doesn't exist at all if
{\tt \_\_WXDEBUG\_\_} is not defined.

\wxheading{Parameters}

\docparam{stream}{Stream on which to output dump information.}

\wxheading{Remarks}

Currently wxWidgets does not define Dump for derived classes, but
programmers may wish to use it for their own applications. Be sure to
call the Dump member of the class's base class to allow all information to be
dumped.

The implementation of this function in wxObject just writes the class name of
the object.

\membersection{wxObject::GetClassInfo}\label{wxobjectgetclassinfo}

\func{wxClassInfo *}{GetClassInfo}{\void}

This virtual function is redefined for every class that requires run-time
type information, when using DECLARE\_CLASS macros.

\membersection{wxObject::GetRefData}\label{wxobjectgetrefdata}

\constfunc{wxObjectRefData*}{GetRefData}{\void}

Returns the {\bf m\_refData} pointer.

\wxheading{See also}

\helpref{wxObject::Ref}{wxobjectref}, \helpref{wxObject::UnRef}{wxobjectunref}, \helpref{wxObject::m\_refData}{wxobjectmrefdata},\rtfsp
\helpref{wxObject::SetRefData}{wxobjectsetrefdata},\rtfsp
\helpref{wxObjectRefData}{wxobjectrefdata}

\membersection{wxObject::IsKindOf}\label{wxobjectiskindof}

\func{bool}{IsKindOf}{\param{wxClassInfo *}{info}}

Determines whether this class is a subclass of (or the same class as)
the given class.

\wxheading{Parameters}

\docparam{info}{A pointer to a class information object, which may be obtained
by using the CLASSINFO macro.}

\wxheading{Return value}

true if the class represented by {\it info} is the same class as
this one or is derived from it.

\wxheading{Example}

\begin{verbatim}
  bool tmp = obj->IsKindOf(CLASSINFO(wxFrame));
\end{verbatim}

\membersection{wxObject::IsSameAs}\label{wxobjectissameas}

\func{bool}{IsSameAs}{\param{const wxObject\& }{ obj}}

Returns \true if this object has the same data pointer as \arg{obj}. Notice
that \true is returned if the data pointers are \NULL in both objects.

This function only does a \emph{shallow} comparison, i.e. it doesn't compare
the objects pointed to by the data pointers of these objects.

\membersection{wxObject::Ref}\label{wxobjectref}

\func{void}{Ref}{\param{const wxObject\& }{clone}}

Makes this object refer to the data in {\it clone}.

\wxheading{Parameters}

\docparam{clone}{The object to `clone'.}

\wxheading{Remarks}

First this function calls \helpref{wxObject::UnRef}{wxobjectunref} on itself
to decrement (and perhaps free) the data it is currently referring to.

It then sets its own m\_refData to point to that of {\it clone}, and increments the reference count
inside the data.

\wxheading{See also}

\helpref{wxObject::UnRef}{wxobjectunref}, \helpref{wxObject::m\_refData}{wxobjectmrefdata},\rtfsp
\helpref{wxObject::SetRefData}{wxobjectsetrefdata}, \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp
\helpref{wxObjectRefData}{wxobjectrefdata}

\membersection{wxObject::SetRefData}\label{wxobjectsetrefdata}

\func{void}{SetRefData}{\param{wxObjectRefData*}{ data}}

Sets the {\bf m\_refData} pointer.

\wxheading{See also}

\helpref{wxObject::Ref}{wxobjectref}, \helpref{wxObject::UnRef}{wxobjectunref}, \helpref{wxObject::m\_refData}{wxobjectmrefdata},\rtfsp
\helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp
\helpref{wxObjectRefData}{wxobjectrefdata}

\membersection{wxObject::UnRef}\label{wxobjectunref}

\func{void}{UnRef}{\void}

Decrements the reference count in the associated data, and if it is zero, deletes the data.
The {\bf m\_refData} member is set to NULL.

\wxheading{See also}

\helpref{wxObject::Ref}{wxobjectref}, \helpref{wxObject::m\_refData}{wxobjectmrefdata},\rtfsp
\helpref{wxObject::SetRefData}{wxobjectsetrefdata}, \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp
\helpref{wxObjectRefData}{wxobjectrefdata}

\membersection{wxObject::UnShare}\label{wxobjectunshare}

\func{void}{UnShare}{\void}

Ensure that this object's data is not shared with any other object.

if we have no
data, it is created using CreateRefData() below, if we have shared data
it is copied using CloneRefData(), otherwise nothing is done.


\membersection{wxObject::operator new}\label{wxobjectnew}

\func{void *}{new}{\param{size\_t }{size}, \param{const wxString\& }{filename = NULL}, \param{int}{ lineNum = 0}}

The {\it new} operator is defined for debugging versions of the library only, when
the identifier \_\_WXDEBUG\_\_ is defined. It takes over memory allocation, allowing
wxDebugContext operations.

\membersection{wxObject::operator delete}\label{wxobjectdelete}

\func{void}{delete}{\param{void }{buf}}

The {\it delete} operator is defined for debugging versions of the library only, when
the identifier \_\_WXDEBUG\_\_ is defined. It takes over memory deallocation, allowing
wxDebugContext operations.



%% wxObjectRefData

\section{\class{wxObjectRefData}}\label{wxobjectrefdata}

This class is used to store reference-counted data. Derive classes from this to
store your own data. When retrieving information from a {\bf wxObject}'s reference data,
you will need to cast to your own derived class.

\wxheading{Friends}

\helpref{wxObject}{wxobject}

\wxheading{See also}

\helpref{wxObject}{wxobject}
\helpref{wxObjectDataPtr<T>}{wxobjectdataptr}
\helpref{Reference counting}{trefcount}

\wxheading{Derived from}

No base class

\wxheading{Include files}

<wx/object.h>

\wxheading{Example}

\begin{verbatim}

// include file

class MyCar: public wxObject
{
public:
    MyCar() { }
    MyCar( int price );
    
    bool IsOk() const { return m_refData != NULL; }

    bool operator == ( const MyCar& car ) const;
    bool operator != (const MyCar& car) const { return !(*this == car); }

    void SetPrice( int price );
    int GetPrice() const;

protected:
    virtual wxObjectRefData *CreateRefData() const;
    virtual wxObjectRefData *CloneRefData(const wxObjectRefData *data) const;

    DECLARE_DYNAMIC_CLASS(MyCar)
};


// implementation

class MyCarRefData: public wxObjectRefData
{
public:
    MyCarRefData()
    {
        m_price = 0;
    }

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

    bool operator == (const MyCarRefData& data) const
    {
        return m_price == data.m_price;
    }

    int m_price;
};


#define M_CARDATA ((MyCarRefData *)m_refData)

IMPLEMENT_DYNAMIC_CLASS(MyCar,wxObject)

MyCar::MyCar( int price )
{
    m_refData = new MyCarRefData();
    M_CARDATA->m_price = price;
}

wxObjectRefData *MyCar::CreateRefData() const
{
    return new MyCarRefData;
}

wxObjectRefData *MyCar::CloneRefData(const wxObjectRefData *data) const
{
    return new MyCarRefData(*(MyCarRefData *)data);
}

bool MyCar::operator == ( const MyCar& car ) const
{
    if (m_refData == car.m_refData) return true;

    if (!m_refData || !car.m_refData) return false;

    return ( *(MyCarRefData*)m_refData == *(MyCarRefData*)car.m_refData );
}

void MyCar::SetPrice( int price )
{
    UnShare();

    M_CARDATA->m_price = price;
}

int MyCar::GetPrice() const
{
    wxCHECK_MSG( IsOk(), -1, "invalid car" );
    
    return (M_CARDATA->m_price);
}

\end{verbatim}

\wxheading{Library}

\helpref{wxBase}{librarieslist}

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


\membersection{wxObjectRefData::wxObjectRefData}\label{wxobjectrefdatactor}

\func{}{wxObjectRefData}{\void}

Default constructor. Initialises the internal reference count to 1.

\membersection{wxObjectRefData::\destruct{wxObjectRefData}}\label{wxobjectrefdatadtor}

\func{}{wxObjectRefData}{\void}

Destructor. It's declared {\tt protected} so that wxObjectRefData instances will never
be destroyed directly but only as result of a \helpref{DecRef}{wxobjectrefdatadecref} call.

\membersection{wxObjectRefData::GetRefCount}\label{wxobjectrefdatagetrefcount}

\constfunc{int}{GetRefCount}{\void}

Returns the reference count associated with this shared data.
When this goes to zero during a \helpref{DecRef}{wxobjectrefdatadecref} call, the object
will auto-free itself.

\membersection{wxObjectRefData::DecRef}\label{wxobjectrefdatadecref}

\func{void}{DecRef}{\void}

Decrements the reference count associated with this shared data and, if it reaches zero,
destroys this instance of wxObjectRefData releasing its memory.

Please note that after calling this function, the caller should absolutely avoid to use
the pointer to this instance since it may not be valid anymore.

\membersection{wxObjectRefData::IncRef}\label{wxobjectrefdataincref}

\func{void}{IncRef}{\void}

Increments the reference count associated with this shared data.