Fix broken and missing DataView interface items for Phoenix

[wxWidgets.git] / docs / doxygen / overviews / refcount.h

diff --git a/docs/doxygen/overviews/refcount.h b/docs/doxygen/overviews/refcount.h
index be24a53e5ececdd9b5d07ddaa6a82121dd4336b9..bcddbd5e7d4003c59334e4c6a161f8641bb63d28 100644 (file)
--- a/docs/doxygen/overviews/refcount.h
+++ b/docs/doxygen/overviews/refcount.h
@@ -3,24 +3,14 @@
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /////////////////////////////////////////////////////////////////////////////
 

-/*!
+/**

 
 @page overview_refcount Reference Counting
 
 
 @page overview_refcount Reference Counting
 

-@li @ref overview_refcount_ignore
-@li @ref overview_refcount_equality
-@li @ref overview_refcount_destruct
-@li @ref overview_refcount_list
-@li @ref overview_refcount_object
-
-
-<hr>
-
-
-@section overview_refcount_ignore Why You Shouldn't Care About It
+@tableofcontents

 
 Many wxWidgets objects use a technique known as <em>reference counting</em>,
 also known as <em>copy on write</em> (COW). This means that when an object is
 
 Many wxWidgets objects use a technique known as <em>reference counting</em>,
 also known as <em>copy on write</em> (COW). This means that when an object is


@@ -41,19 +31,20 @@ operation on it is the same.
 
 @section overview_refcount_equality Object Comparison
 
 
 @section overview_refcount_equality Object Comparison
 

-The == and != operators of the reference counted classes always do a @c deep
-comparison. This means that the equality operator will return @true if two
-objects are identical and not only if they share the same data.
+The == and != operators of @ref overview_refcount_list "the reference counted classes"
+always do a <em>deep comparison</em>. This means that the equality operator
+will return @true if two objects are identical and not only if they share the
+same data.

 
 Note that wxWidgets follows the <em>STL philosophy</em>: when a comparison
 
 Note that wxWidgets follows the <em>STL philosophy</em>: when a comparison

-operator can not be implemented efficiently (like for e.g. wxImage's ==
+operator cannot be implemented efficiently (like for e.g. wxImage's ==

 operator which would need to compare the entire image's data, pixel-by-pixel),
 it's not implemented at all. That's why not all reference counted classes
 provide comparison operators.
 
 Also note that if you only need to do a @c shallow comparison between two
 wxObject derived classes, you should not use the == and != operators but
 operator which would need to compare the entire image's data, pixel-by-pixel),
 it's not implemented at all. That's why not all reference counted classes
 provide comparison operators.
 
 Also note that if you only need to do a @c shallow comparison between two
 wxObject derived classes, you should not use the == and != operators but

-rather the wxObject::IsSameAs function.
+rather the wxObject::IsSameAs() function.

 
 
 @section overview_refcount_destruct Object Destruction
 
 
 @section overview_refcount_destruct Object Destruction


@@ -77,6 +68,12 @@ operators and copy constructors since they are reference-counted:
 @li wxBrush
 @li wxCursor
 @li wxFont
 @li wxBrush
 @li wxCursor
 @li wxFont

+@li wxGraphicsBrush
+@li wxGraphicsContext
+@li wxGraphicsFont
+@li wxGraphicsMatrix
+@li wxGraphicsPath
+@li wxGraphicsPen

 @li wxIcon
 @li wxImage
 @li wxMetafile
 @li wxIcon
 @li wxImage
 @li wxMetafile


@@ -90,14 +87,20 @@ operators and copy constructors since they are reference-counted:
 Note that the list above reports the objects which are reference counted in all
 ports of wxWidgets; some ports may use this technique also for other classes.
 
 Note that the list above reports the objects which are reference counted in all
 ports of wxWidgets; some ports may use this technique also for other classes.
 

+All the objects implement a function @b IsOk() to test if they are referencing
+valid data; when the objects are in uninitialized state, you can only use the
+@b IsOk() getter; trying to call any other getter, e.g. wxBrush::GetStyle() on
+the ::wxNullBrush object, will result in an assert failure in debug builds.
+

 
 @section overview_refcount_object Making Your Own Reference Counted Class
 
 
 @section overview_refcount_object Making Your Own Reference Counted Class
 

-Reference counting can be implemented easily using wxObject and wxObjectRefData
-classes. Alternatively, you can also use the wxObjectDataPtr<T> template.
+Reference counting can be implemented easily using wxObject or using the
+intermediate wxRefCounter class directly.  Alternatively, you can also use the
+wxObjectDataPtr<T> template.

 
 

-First, derive a new class from wxObjectRefData and put there the
-memory-consuming data.
+First, derive a new class from wxRefCounter (or wxObjectRefData when using a
+wxObject derived class) and put the memory-consuming data in it.

 
 Then derive a new class from wxObject and implement there the public interface
 which will be seen by the user of your class. You'll probably want to add a
 
 Then derive a new class from wxObject and implement there the public interface
 which will be seen by the user of your class. You'll probably want to add a


@@ -115,9 +118,8 @@ In fact, any time you need to read the data from your wxObject-derived class,
 you will need to call this function.
 
 @note Any time you need to actually modify the data placed inside your wxObject
 you will need to call this function.
 
 @note Any time you need to actually modify the data placed inside your wxObject

-derived class, you must first call the wxObject::UnShare function to ensure
+derived class, you must first call the wxObject::UnShare() function to ensure

 that the modifications won't affect other instances which are eventually
 sharing your object's data.
 
 */
 that the modifications won't affect other instances which are eventually
 sharing your object's data.
 
 */

-