Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doxygen topic overview cleanups.

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52088 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Bryan Petty
2008-02-25 10:50:43 +00:00
parent ed8c374dd7
commit 728449503c
4 changed files with 825 additions and 1365 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/doxygen/mainpages/topics.h
View File

@@ -37,7 +37,7 @@
@li @subpage overview_backwardcompat @li @subpage overview_backwardcompat
@li @subpage overview_runtimeclass @li @subpage overview_runtimeclass
@li @subpage overview_trefcount @li @subpage overview_refcount
@li @subpage overview_app @li @subpage overview_app
@li @subpage overview_unicode @li @subpage overview_unicode
@li @subpage overview_mbconvclasses @li @subpage overview_mbconvclasses
@@ -63,7 +63,7 @@
@li @subpage overview_thread @li @subpage overview_thread
@li @subpage overview_config @li @subpage overview_config
@li @subpage overview_fs @li @subpage overview_fs
@li @subpage overview_resyn @li @subpage overview_resyntax
@li @subpage overview_arc @li @subpage overview_arc
@li @subpage overview_ipc @li @subpage overview_ipc

161
docs/doxygen/overviews/refcount.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: trefcount // Name: refcount.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,114 +8,117 @@
/*! /*!
@page trefcount_overview Reference counting @page overview_refcount Reference Counting
@ref refcount_overview @li @ref overview_refcount_ignore
@ref refcountequality_overview @li @ref overview_refcount_equality
@ref refcountdestruct_overview @li @ref overview_refcount_destruct
@ref refcountlist_overview @li @ref overview_refcount_list
@ref object_overview @li @ref overview_refcount_object
@section refcount Why you shouldn't care about it <hr>
@section overview_refcount_ignore Why You Shouldn't Care About It
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
assigned to another, no copying really takes place. Only the reference count on
the shared object data is incremented and both objects share the same data (a
very fast operation).
Many wxWidgets objects use a technique known as @e reference counting, also known
as @e copy on write (COW).
This means that when an object is assigned to another, no copying really takes place:
only the reference count on the shared object data is incremented and both objects
share the same data (a very fast operation).
But as soon as one of the two (or more) objects is modified, the data has to be But as soon as one of the two (or more) objects is modified, the data has to be
copied because the changes to one of the objects shouldn't be seen in the copied because the changes to one of the objects shouldn't be seen in the
others. As data copying only happens when the object is written to, this is others. As data copying only happens when the object is written to, this is
known as COW. known as COW.
What is important to understand is that all this happens absolutely What is important to understand is that all this happens absolutely
transparently to the class users and that whether an object is shared or not transparently to the class users and that whether an object is shared or not is
is not seen from the outside of the class - in any case, the result of any not seen from the outside of the class - in any case, the result of any
operation on it is the same. operation on it is the same.
@section refcountequality Object comparison
The == and != operators of @ref refcountlist_overview @section overview_refcount_equality Object Comparison
always do a @c deep comparison.
This means that the equality operator will return @true if two objects are The == and != operators of the reference counted classes always do a @c deep
identic and not only if they share the same data. comparison. This means that the equality operator will return @true if two
Note that wxWidgets follows the @e STL philosophy: when a comparison operator cannot objects are identical and not only if they share the same data.
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. Note that wxWidgets follows the <em>STL philosophy</em>: when a comparison
That's why not all reference-counted wxWidgets classes provide comparison operators. operator can not 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 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 #wxObject derived classes, you should not use the == and != operators but
but rather the wxObject::IsSameAs function. rather the wxObject::IsSameAs function.
@section refcountdestruct Object destruction @section overview_refcount_destruct Object Destruction
When a COW object destructor is called, it may not delete the data: if it's shared, When a COW object destructor is called, it may not delete the data: if it's
the destructor will just decrement the shared data's reference count without destroying it. shared, the destructor will just decrement the shared data's reference count
Only when the destructor of the last object owning the data is called, the data is really without destroying it. Only when the destructor of the last object owning the
destroyed. As for all other COW-things, this happens transparently to the class users so data is called, the data is really destroyed. Just like all other COW-things,
that you shouldn't care about it. this happens transparently to the class users so that you shouldn't care about
it.
@section refcountlist List of reference-counted wxWidgets classes @section overview_refcount_list List of Reference Counted Classes
The following classes in wxWidgets have efficient (i.e. fast) assignment operators The following classes in wxWidgets have efficient (i.e. fast) assignment
and copy constructors since they are reference-counted: operators and copy constructors since they are reference-counted:
#wxAcceleratorTable
#wxAnimation @li #wxAcceleratorTable
@li #wxAnimation
@li #wxBitmap
@li #wxBrush
@li #wxCursor
@li #wxFont
@li #wxIcon
@li #wxImage
@li #wxMetafile
@li #wxPalette
@li #wxPen
@li #wxRegion
@li #wxString
@li #wxVariant
@li #wxVariantData
#wxBitmap 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.
#wxBrush
#wxCursor @section overview_refcount_object Making Your Own Reference Counted Class
#wxFont Reference counting can be implemented easily using #wxObject and
#wxObjectRefData classes. Alternatively, you can also use the
#wxObjectDataPtr<T> template.
#wxIcon First, derive a new class from #wxObjectRefData and put there the
memory-consuming data.
#wxImage 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
#wxMetafile function to your class which does the cast from #wxObjectRefData to your
class-specific shared data. For example:
#wxPalette
#wxPen
#wxRegion
#wxString
#wxVariant
#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.
@section wxobjectoverview Make your own reference-counted class
Reference counting can be implemented easily using #wxObject
and #wxObjectRefData classes. Alternatively, you
can also use the #wxObjectDataPtrT template.
First, derive a new class from #wxObjectRefData and
put there the memory-consuming data.
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 function to your class which does the cast from
#wxObjectRefData to your class-specific shared data; e.g.:
@code @code
MyClassRefData *GetData() const { return wx_static_cast(MyClassRefData*, m_refData); } MyClassRefData* GetData() const
{
return wx_static_cast(MyClassRefData*, m_refData);
}
@endcode @endcode
in fact, all times you'll need to read the data from your wxObject-derived class, In fact, any time you need to read the data from your wxObject-derived class,
you'll need to call such function. you will need to call this function.
Very important, all times you need to actually modify the data placed inside your
wxObject-derived class, you must first call the wxObject::UnShare @note Any time you need to actually modify the data placed inside your wxObject
function to be sure that the modifications won't affect other instances which are derived class, you must first call the wxObject::UnShare function to ensure
eventually sharing your object's data. that the modifications won't affect other instances which are eventually
sharing your object's data.
*/ */

37
docs/doxygen/overviews/referencenotes.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: referencenotes // Name: referencenotes.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,25 +8,24 @@
/*! /*!
@page referencenotes_overview Notes on using the reference @page overview_referencenotes Notes on Using the Reference
In the descriptions of the wxWidgets classes and their member In the descriptions of the wxWidgets classes and their member functions, note
functions, note that descriptions of inherited member functions are not that descriptions of inherited member functions are not duplicated in derived
duplicated in derived classes unless their behaviour is different. So in classes unless their behaviour is different. So in using a class such as
using a class such as wxScrolledWindow, be aware that wxWindow functions may be wxScrolledWindow, be aware that wxWindow functions may be relevant.
relevant.
Note also that arguments with default values may be omitted from a Note also that arguments with default values may be omitted from a function
function call, for brevity. Size and position arguments may usually be call, for brevity. Size and position arguments may usually be given a value of
given a value of -1 (the default), in which case wxWidgets will choose a -1 (the default), in which case wxWidgets will choose a suitable value.
suitable value.
Most strings are returned as wxString objects. However, for remaining Most strings are returned as wxString objects. However, for remaining char *
char * return values, the strings are allocated and return values, the strings are allocated and deallocated by wxWidgets.
deallocated by wxWidgets. Therefore, return values should always be Therefore, return values should always be copied for long-term use, especially
copied for long-term use, especially since the same buffer is often since the same buffer is often used by wxWidgets.
used by wxWidgets.
The member functions are given in alphabetical order except for The member functions are given in alphabetical order except for constructors
constructors and destructors which appear first. and destructors which appear first.
*/ */

612
docs/doxygen/overviews/resyntax.h
View File

File diff suppressed because it is too large Load Diff