Doc update.

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

diff --git a/docs/latex/wx/trefcount.tex b/docs/latex/wx/trefcount.tex
index a5f9592c0fc0f65079f95421dac722aab7dd9889..d240a690e3d0769573e3d293ccfe644a5a647e9e 100644 (file)
--- a/docs/latex/wx/trefcount.tex
+++ b/docs/latex/wx/trefcount.tex
@@ -1,6 +1,6 @@
 \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).
@@ -18,6 +18,33 @@ 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.
 
+\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::IsSameAs}{wxobjectissameas} 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}
@@ -26,19 +53,23 @@ The following classes in wxWidgets have efficient (i.e. fast) assignment operato
 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{wxIcon}{wxicon}\\
 \helpref{wxImage}{wximage}\\
 \helpref{wxMetafile}{wxmetafile}\\
 \helpref{wxPalette}{wxpalette}\\
 \helpref{wxPen}{wxpen}\\
 \helpref{wxRegion}{wxregion}\\
-\helpref{wxRegionIterator}{wxregioniterator}\\
-\helpref{wxString}{wxstring}
-
-
+\helpref{wxString}{wxstring}\\
+\helpref{wxVariant}{wxvariant}\\
+\helpref{wxVariantData}{wxvariantdata}
 
+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}
@@ -60,7 +91,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
-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.