remove just added wxCoordRound() (see patch 1586499)

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

diff --git a/docs/latex/wx/trefcount.tex b/docs/latex/wx/trefcount.tex
index a5f9592c0fc0f65079f95421dac722aab7dd9889..eb280c5c78be331987e581696e6a6548e0883202 100644 (file)
--- a/docs/latex/wx/trefcount.tex
+++ b/docs/latex/wx/trefcount.tex
@@ -1,6 +1,6 @@
 \section{Reference counting}\label{trefcount}
 
 \section{Reference counting}\label{trefcount}
 

-\subsection{Reference counting and why you shouldn't care about it}\label{refcount}
+\subsection{Why you shouldn't care about it}\label{refcount}

 
 Many wxWidgets objects use a technique known as \it{reference counting}, also known
 as {\it copy on write} (COW).
 
 Many wxWidgets objects use a technique known as \it{reference counting}, also known
 as {\it copy on write} (COW).


@@ -18,27 +18,55 @@ transparently to the class users and that whether an object is shared or not
 is not seen from the outside of the class - in any case, the result of any
 operation on it is the same.
 
 is not seen from the outside of the class - in any case, the result of any
 operation on it is the same.
 

+\subsection{List of reference-counted wxWidgets classes}\label{refcountlist}
+\subsection{Object comparison}\label{refcountequality}

 
 

+The $==$ and $!=$ operators of \helpref{wxWidgets COW objects}{refcountlist}
+always do a {\tt deep} comparison.
+
+This means that the equality operator will return \true if two objects are
+identic and not only if they share the same data.
+
+Note that wxWidgets follows the {\it STL philosophy}: when a comparison operator cannot
+be implemented efficiently (like for e.g. wxImage's $==$ operator which would need to
+compare pixel-by-pixel the entire image's data), it's not implemented at all.
+
+That's why not all reference-counted wxWidgets classes provide comparison operators.
+
+Also note that if you only need to do a {\tt shallow} comparison between two
+\helpref{wxObject}{wxobject}-derived classes, you should not use the $==$ and $!=$ operators
+but rather the \helpref{wxObject::IsRefTo}{wxobjectisrefto} function.
+
+
+\subsection{Object destruction}\label{refcountdestruct}
+
+When a COW object destructor is called, it may not delete the data: if it's shared,
+the destructor will just decrement the shared data's reference count without destroying it.
+
+Only when the destructor of the last object owning the data is called, the data is really
+destroyed. As for all other COW-things, this happens transparently to the class users so
+that you shouldn't care about it.

 
 

-\subsection{List of reference-counted wxWidgets classes}\label{refcountlist}

 
 The following classes in wxWidgets have efficient (i.e. fast) assignment operators
 and copy constructors since they are reference-counted:
 
 \helpref{wxAcceleratorTable}{wxacceleratortable}\\
 
 The following classes in wxWidgets have efficient (i.e. fast) assignment operators
 and copy constructors since they are reference-counted:
 
 \helpref{wxAcceleratorTable}{wxacceleratortable}\\

+\helpref{wxAnimation}{wxanimation}\\
+\helpref{wxBitmap}{wxbitmap}\\

 \helpref{wxBrush}{wxbrush}\\
 \helpref{wxCursor}{wxcursor}\\
 \helpref{wxFont}{wxfont}\\
 \helpref{wxBrush}{wxbrush}\\
 \helpref{wxCursor}{wxcursor}\\
 \helpref{wxFont}{wxfont}\\

+\helpref{wxIcon}{wxicon}\\

 \helpref{wxImage}{wximage}\\
 \helpref{wxMetafile}{wxmetafile}\\
 \helpref{wxPalette}{wxpalette}\\
 \helpref{wxPen}{wxpen}\\
 \helpref{wxRegion}{wxregion}\\
 \helpref{wxImage}{wximage}\\
 \helpref{wxMetafile}{wxmetafile}\\
 \helpref{wxPalette}{wxpalette}\\
 \helpref{wxPen}{wxpen}\\
 \helpref{wxRegion}{wxregion}\\

-\helpref{wxRegionIterator}{wxregioniterator}\\

 \helpref{wxString}{wxstring}
 
 \helpref{wxString}{wxstring}
 

-
-
+Note that the list above reports the objects which are reference-counted in all ports of
+wxWidgets; some ports may use this tecnique also for other classes.

 \subsection{Make your own reference-counted class}\label{wxobjectoverview}
 
 Reference counting can be implemented easily using \helpref{wxObject}{wxobject}
 \subsection{Make your own reference-counted class}\label{wxobjectoverview}
 
 Reference counting can be implemented easily using \helpref{wxObject}{wxobject}


@@ -60,7 +88,7 @@ in fact, all times you'll need to read the data from your wxObject-derived class
 you'll need to call such function.
 
 Very important, all times you need to actually modify the data placed inside your
 you'll need to call such function.
 
 Very important, all times you need to actually modify the data placed inside your

-wxObject-derived class, you must first call the \helpref{wxObject::UnShare}{wxobjectunshare}
+wxObject-derived class, you must first call the wxObject::UnShare

 function to be sure that the modifications won't affect other instances which are
 eventually sharing your object's data.
 
 function to be sure that the modifications won't affect other instances which are
 eventually sharing your object's data.