984daa2a57
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52051 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
81 lines
3.8 KiB
C
81 lines
3.8 KiB
C
/////////////////////////////////////////////////////////////////////////////
|
|
// Name: windowids
|
|
// Purpose: topic overview
|
|
// Author: wxWidgets team
|
|
// RCS-ID: $Id$
|
|
// Licence: wxWindows license
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*!
|
|
|
|
@page overview_windowids Window IDs overview
|
|
|
|
@seealso
|
|
#wxIdManager
|
|
wxWindow::NewControlId
|
|
wxWindow::UnreserveControlId
|
|
|
|
@li @ref introduction
|
|
@li @ref overview_windowidstypes
|
|
@li @ref overview_windowidsusing
|
|
|
|
|
|
@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.
|
|
|
|
*/
|
|
|
|
|