[ 1578529 ] better docs for reference-counted objects

This already includes the change for wxBitmap, which
  is not COW yet.


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

docs/latex/wx/accel.tex

@@ -119,7 +119,7 @@ Default constructor.
 
 \func{}{wxAcceleratorTable}{\param{const wxAcceleratorTable\& }{bitmap}}
 
-Copy constructor.
+Copy constructor, uses \helpref{reference counting}{trefcount}.
 
 \func{}{wxAcceleratorTable}{\param{int}{ n}, \param{wxAcceleratorEntry}{ entries[]}}
 
@@ -161,9 +161,7 @@ Returns true if the accelerator table is valid.
 
 \func{wxAcceleratorTable\& }{operator $=$}{\param{const wxAcceleratorTable\& }{accel}}
 
-Assignment operator. This operator does not copy any data, but instead
+Assignment operator, using \helpref{reference counting}{trefcount}.
-passes a pointer to the data in {\it accel} and increments a reference
-counter. It is a fast operation.
 
 \wxheading{Parameters}
 

docs/latex/wx/bitmap.tex

@@ -38,10 +38,8 @@ Default constructor.
 
 \func{}{wxBitmap}{\param{const wxBitmap\& }{bitmap}}
 
-Copy constructor. Note that this does not take a fresh copy of the data,
+Copy constructor, uses \helpref{reference counting}{trefcount}.
-but instead makes the internal data point to {\it bitmap}'s data. So
+To make a real copy, you can use:
-changing one bitmap will change the other. To make a real copy, you can
-use:
 
 \begin{verbatim}
     wxBitmap newBitmap = oldBitmap.GetSubBitmap(
@@ -587,9 +585,7 @@ Sets the width member (does not affect the bitmap data).
 
 \func{wxBitmap\& }{operator $=$}{\param{const wxBitmap\& }{bitmap}}
 
-Assignment operator. This operator does not copy any data, but instead
+Assignment operator, using \helpref{reference counting}{trefcount}.
-passes a pointer to the data in {\it bitmap} and increments a reference
-counter. It is a fast operation.
 
 \wxheading{Parameters}
 

docs/latex/wx/brush.tex

@@ -95,7 +95,7 @@ Constructs a stippled brush using a bitmap.
 
 \func{}{wxBrush}{\param{const wxBrush\&}{ brush}}
 
-Copy constructor. This uses reference counting so is a cheap operation.
+Copy constructor, uses \helpref{reference counting}{trefcount}.
 
 \wxheading{Parameters}
 
@@ -293,8 +293,7 @@ Sets the brush style.
 
 \func{wxBrush\&}{operator $=$}{\param{const wxBrush\& }{brush}}
 
-Assignment operator, using reference counting. Returns a reference
+Assignment operator, using \helpref{reference counting}{trefcount}.
-to `this'.
 
 
 \membersection{wxBrush::operator $==$}\label{wxbrushequals}

docs/latex/wx/cursor.tex

@@ -84,7 +84,7 @@ On MacOS if the cursor is larger than 16x16 it is resized and currently only sho
 
 \func{}{wxCursor}{\param{const wxCursor\&}{ cursor}}
 
-Copy constructor. This uses reference counting so is a cheap operation.
+Copy constructor, uses \helpref{reference counting}{trefcount}.
 
 \wxheading{Parameters}
 
@@ -244,8 +244,7 @@ Returns true if cursor data is present.
 
 \func{wxCursor\&}{operator $=$}{\param{const wxCursor\& }{cursor}}
 
-Assignment operator, using reference counting. Returns a reference
+Assignment operator, using \helpref{reference counting}{trefcount}.
-to `this'.
 
 \membersection{wxCursor::operator $==$}\label{wxcursorequals}
 

docs/latex/wx/font.tex

@@ -165,6 +165,10 @@ wxSWISS\_FONT}
 
 Default constructor.
 
+\func{}{wxFont}{\param{const wxFont\&}{ font}}
+
+Copy constructor, uses \helpref{reference counting}{trefcount}.
+
 \func{}{wxFont}{\param{int}{ pointSize}, \param{wxFontFamily}{ family}, \param{int}{ style}, \param{wxFontWeight}{ weight},
  \param{const bool}{ underline = false}, \param{const wxString\& }{faceName = ""},
  \param{wxFontEncoding }{encoding = wxFONTENCODING\_DEFAULT}}
@@ -578,8 +582,7 @@ Sets the font weight.
 
 \func{wxFont\&}{operator $=$}{\param{const wxFont\& }{font}}
 
-Assignment operator, using reference counting. Returns a reference
+Assignment operator, using \helpref{reference counting}{trefcount}.
-to `this'.
 
 
 \membersection{wxFont::operator $==$}\label{wxfontequals}

docs/latex/wx/image.tex

@@ -95,7 +95,7 @@ Default constructor.
 
 \func{}{wxImage}{\param{const wxImage\& }{image}}
 
-Copy constructor.
+Copy constructor, uses \helpref{reference counting}{trefcount}.
 
 \func{}{wxImage}{\param{const wxBitmap\&}{ bitmap}}
 
@@ -1290,9 +1290,7 @@ data.
 
 \func{wxImage\& }{operator $=$}{\param{const wxImage\& }{image}}
 
-Assignment operator. This operator does not copy any data, but instead
+Assignment operator, using \helpref{reference counting}{trefcount}.
-passes a pointer to the data in {\it image} and increments a reference
-counter. It is a fast operation.
 
 \wxheading{Parameters}
 

docs/latex/wx/object.tex

@@ -12,8 +12,8 @@ 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 reference counted objects, such as
+wxObject can be used to implement \helpref{reference counted}{trefcount} objects,
-wxPen, wxBitmap and others.
+such as wxPen, wxBitmap and others (see \helpref{this list}{refcountlist}).
 
 \wxheading{See also}
 
@@ -197,12 +197,6 @@ you will need to cast to your own derived class.
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
-\membersection{wxObjectRefData::m\_count}\label{wxobjectrefdatamcount}
-
-\member{int}{m\_count}
-
-Reference count. When this goes to zero during a \helpref{wxObject::UnRef}{wxobjectunref}, an object
-can delete the {\bf wxObjectRefData} object.
 
 \membersection{wxObjectRefData::wxObjectRefData}\label{wxobjectrefdatactor}
 
@@ -216,4 +210,11 @@ Default constructor. Initialises the {\bf m\_count} member to 1.
 
 Destructor.
 
+\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{wxObject::UnRef}{wxobjectunref}, an object
+can delete this {\bf wxObjectRefData} object.
 

docs/latex/wx/palette.tex

@@ -54,7 +54,7 @@ Default constructor.
 
 \func{}{wxPalette}{\param{const wxPalette\&}{ palette}}
 
-Copy constructor. This uses reference counting so is a cheap operation.
+Copy constructor, uses \helpref{reference counting}{trefcount}.
 
 \func{}{wxPalette}{\param{int}{ n}, \param{const unsigned char* }{red},\\
  \param{const unsigned char* }{green}, \param{const unsigned char* }{blue}}
@@ -180,8 +180,7 @@ Returns true if palette data is present.
 
 \func{wxPalette\&}{operator $=$}{\param{const wxPalette\& }{palette}}
 
-Assignment operator, using reference counting. Returns a reference
+Assignment operator, using \helpref{reference counting}{trefcount}.
-to `this'.
 
 \membersection{wxPalette::operator $==$}\label{wxpaletteequals}
 

docs/latex/wx/pen.tex

@@ -93,7 +93,7 @@ Constructs a stippled pen from a stipple bitmap and a width.
 
 \func{}{wxPen}{\param{const wxPen\&}{ pen}}
 
-Copy constructor. This uses reference counting so is a cheap operation.
+Copy constructor, uses \helpref{reference counting}{trefcount}.
 
 \wxheading{Parameters}
 
@@ -329,8 +329,7 @@ Sets the pen width.
 
 \func{wxPen\&}{operator $=$}{\param{const wxPen\& }{pen}}
 
-Assignment operator, using reference counting. Returns a reference
+Assignment operator, using \helpref{reference counting}{trefcount}.
-to `this'.
 
 \membersection{wxPen::operator $==$}\label{wxpenequals}
 

docs/latex/wx/region.tex

@@ -39,7 +39,7 @@ Constructs a rectangular region a wxRect object.
 
 \func{}{wxRegion}{\param{const wxRegion\&}{ region}}
 
-Constructs a region by copying another region.
+Copy constructor, uses \helpref{reference counting}{trefcount}.
 
 \func{}{wxRegion}{\param{size\_t}{ n}, \param{const wxPoint }{*points}, \param{int }{fillStyle = wxWINDING\_RULE}}
 
@@ -260,7 +260,9 @@ for any overlapping areas. The result is stored in this region.
 
 \func{void}{operator $=$}{\param{const wxRegion\&}{ region}}
 
-Copies {\it region} by reference counting.
+Assignment operator, using \helpref{reference counting}{trefcount}.
+
+
 
 \section{\class{wxRegionIterator}}\label{wxregioniterator}
 

docs/latex/wx/topics.tex

@@ -4,13 +4,14 @@
 
 This chapter contains a selection of topic overviews.
 
-\input tchanges.tex
+%\input tchanges.tex  --  deprecated: look at docs/changes.txt instead
 \input tusage.tex
 \input tguide.tex
 \input hworld.tex
 \input tsamples.tex
 \input tapp.tex
 \input truntime.tex
+\input trefcount.tex
 \input tstring.tex
 \input tbuffer.tex
 \input tdate.tex
@@ -66,4 +67,3 @@ This chapter contains a selection of topic overviews.
 \input re_syntax.tex
 \input arc.tex
 \input backwardcompat.tex
-

docs/latex/wx/tstring.tex

@@ -167,20 +167,8 @@ vastly better from a performance point of view than a wxObjectArray of wxStrings
 
 \subsection{Reference counting and why you shouldn't care about it}\label{wxstringrefcount}
 
-wxString objects use a technique known as {\it copy on write} (COW). This means
+All considerations for wxObject-derived \helpref{reference counted}{trefcount} objects
-that when a string is assigned to another, no copying really takes place: only
+are valid also for wxString, even if it does not derive from wxObject.
-the reference count on the shared string data is incremented and both strings
-share the same data.
-
-But as soon as one of the two (or more) strings is modified, the data has to be
-copied because the changes to one of the strings shouldn't be seen in the
-others. As data copying only happens when the string is written to, this is
-known as COW.
-
-What is important to understand is that all this happens absolutely
-transparently to the class users and that whether a string 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.
 
 Probably the unique case when you might want to think about reference
 counting is when a string character is taken from a string which is not a