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

More doxygen topic overview cleanup.

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52244 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Bryan Petty
2008-03-02 10:48:31 +00:00
parent 2cd3cc948e
commit 3863c5ebd9
7 changed files with 1048 additions and 1063 deletions
Download Patch File Download Diff File Expand all files Collapse all files

138
docs/doxygen/overviews/windowids.h
View File

@@ -1,5 +1,5 @@
/////////////////////////////////////////////////////////////////////////////
// Name: windowids
// Name: windowids.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
@@ -8,73 +8,81 @@
/*!
@page overview_windowids Window IDs overview
@page overview_windowids Window IDs Overview
@seealso
#wxIdManager
wxWindow::NewControlId
wxWindow::UnreserveControlId
@li @ref overview_windowids_intro
@li @ref overview_windowids_type
@li @ref overview_windowids_using
@li @ref introduction
@li @ref overview_windowidstypes
@li @ref overview_windowidsusing
@seealso
@li wxIdManager
@li wxWindow::NewControlId
@li wxWindow::UnreserveControlId
@section introduction Introduction
Various contols and other parts of wxWidgets need an ID. Sometimes the
ID may be directly provided by the use or have a predefined value, such as
@c wxID_OPEN. Often, however, the value of the ID is unimportant and is
created automatically by calling wxWindow::NewControlId
or by passing @c wxID_ANY as the ID of an object.
There are two ways to generate an ID. One way, is to start at a negative number,
and for each new ID, return the next smallest number. This is fine for systems
that can used the full range of negative numbers for an ID, as this provides
more than enough IDs and it would take a very very long time to run out and
wrap around. However, some systems can not use the full range of the ID value.
Windows, for example, can only use 16 bit IDs, and only has about 32000 possible
automatic IDs that can be generated by wxWindow::NewControlId.
If the program runs long enough, depending on the program itself, using this first
method would cause the IDs to wrap around into the positive ID range and cause possible
clashes with any directly specified ID values.
The other way is to keep track of the IDs returned by wxWindow::NewControlId
and don't return them again until the ID is completely free and not being used by
any other objects. This will make sure that the ID values do not clash with one
another. This is accomplished by keeping a reference count for each of the IDs
that can possibly be returned by wxWindow::NewControlId.
Other IDs are not reference counted.
@section overview_windowidstypes Data types
A wxWindowID is just the integer type for a window ID. It should be used almost
everywhere. To help keep track of the count for the automatically generated IDs,
a new type, wxWindowIDRef exists, that can take the place of wxWindowID where needed.
When an ID is first created, it is marked as reserved. When assigning it to a
wxWindowIDRef, the usage count of the ID is increased, or set to 1 if it is currently
reserved. Assigning the same ID to several wxWindowIDRefs will keep track of the count.
As the wxWindowIDRef gets destroyed or its value changes, it will decrease the count
of the used ID. When there are no more wxWindowIDRef types with the created ID, the
ID is considered free and can then be used again by wxWindow::NewControlId.
If a created ID is not assigned to a wxWindowIDRef, then it remains reserved until it
is unreserved manually with wxWindow::UnreserveControlId.
However, if it is assigned to a wxWindowIDRef, then it will be unreserved automatically
and will be considered free when the count is 0, and should NOT be manually unreserved.
wxWindowIDRef can store both automatic IDs from wxWindow::NewControlId
as well as normal IDs. Reference counting is only done for the automatic IDs. Also,
wxWindowIDRef has conversion operators that allow it to be treated just like a wxWindowID.
@section overview_windowidsusing Using wxWindowIDRef
A wxWindowIDRef should be used in place of a wxWindowID where you want to make sure the
ID is not created again by wxWindow::NewControlId
at least until the wxWindowIDRef is destroyed, usually when the associated object is destroyed.
This is done already for windows, menu items, and tool bar items.
It should only be used in the main thread, as it is not thread safe.
*/
<hr>
@section overview_windowids_intro Introduction
Various contols and other parts of wxWidgets need an ID. Sometimes the ID may
be directly provided by the use or have a predefined value, such as
@c wxID_OPEN. Often, however, the value of the ID is unimportant and is created
automatically by calling wxWindow::NewControlId or by passing @c wxID_ANY as
the ID of an object.
There are two ways to generate an ID. One way, is to start at a negative
number, and for each new ID, return the next smallest number. This is fine for
systems that can used the full range of negative numbers for an ID, as this
provides more than enough IDs and it would take a very very long time to run
out and wrap around. However, some systems can not use the full range of the
ID value. Windows, for example, can only use 16 bit IDs, and only has about
32000 possible automatic IDs that can be generated by wxWindow::NewControlId.
If the program runs long enough, depending on the program itself, using this
first method would cause the IDs to wrap around into the positive ID range and
cause possible clashes with any directly specified ID values.
The other way is to keep track of the IDs returned by wxWindow::NewControlId
and don't return them again until the ID is completely free and not being used
by any other objects. This will make sure that the ID values do not clash with
one another. This is accomplished by keeping a reference count for each of the
IDs that can possibly be returned by wxWindow::NewControlId. Other IDs are not
reference counted.
@section overview_windowids_type Data Types
A wxWindowID is just the integer type for a window ID. It should be used
almost everywhere. To help keep track of the count for the automatically
generated IDs, a new type, wxWindowIDRef exists, that can take the place of
wxWindowID where needed. When an ID is first created, it is marked as reserved.
When assigning it to a wxWindowIDRef, the usage count of the ID is increased,
or set to 1 if it is currently reserved. Assigning the same ID to several
wxWindowIDRefs will keep track of the count. As the wxWindowIDRef gets
destroyed or its value changes, it will decrease the count of the used ID. When
there are no more wxWindowIDRef types with the created ID, the ID is considered
free and can then be used again by wxWindow::NewControlId.
If a created ID is not assigned to a wxWindowIDRef, then it remains reserved
until it is unreserved manually with wxWindow::UnreserveControlId. However, if
it is assigned to a wxWindowIDRef, then it will be unreserved automatically and
will be considered free when the count is 0, and should NOT be manually
unreserved.
wxWindowIDRef can store both automatic IDs from wxWindow::NewControlId as well
as normal IDs. Reference counting is only done for the automatic IDs. Also,
wxWindowIDRef has conversion operators that allow it to be treated just like a
wxWindowID.
@section overview_windowids_using Using wxWindowIDRef
A wxWindowIDRef should be used in place of a wxWindowID where you want to make
sure the ID is not created again by wxWindow::NewControlId at least until the
wxWindowIDRef is destroyed, usually when the associated object is destroyed.
This is done already for windows, menu items, and tool bar items. It should
only be used in the main thread, as it is not thread safe.
*/