Add missing critical section locking before accessing shared variable.

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

diff --git a/docs/doxygen/overviews/windowids.h b/docs/doxygen/overviews/windowids.h
index ae71d5d173806f6f17caa69b90da32ff8546b146..169383f4736a7507713450d29f98cbbddf2a81b3 100644 (file)
--- a/docs/doxygen/overviews/windowids.h
+++ b/docs/doxygen/overviews/windowids.h
@@ -1,75 +1,75 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        windowids
+// Name:        windowids.h

 // 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_windowids Window IDs overview
-
- @b See Also
- #wxIdManager
- wxWindow::NewControlId
- wxWindow::UnreserveControlId
- #Introduction
- @ref windowidstypes_overview
- @ref windowidsusing_overview
-
-
- @section windowidsoverviewintro 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 windowidsoverviewtypes 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 windowidsoverviewusing 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.
-
- */
+/**

 
 

+@page overview_windowids Window IDs

 
 

+@tableofcontents
+
+Various controls and other parts of wxWidgets need an ID.  Sometimes the ID may
+be directly provided by the user 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 use the full range of negative numbers for IDs, 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 cannot 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.
+
+@see wxIdManager, wxWindow::NewControlId(), wxWindow::UnreserveControlId()
+
+
+@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 and
+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.
+
+*/