]> git.saurik.com Git - wxWidgets.git/blame - docs/doxygen/overviews/windowids.h
extracted the part of ProcessEvent() which is repeated multiple times during the...
[wxWidgets.git] / docs / doxygen / overviews / windowids.h
CommitLineData
15b6757b 1/////////////////////////////////////////////////////////////////////////////
3863c5eb 2// Name: windowids.h
15b6757b
FM
3// Purpose: topic overview
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
880efa2a 9/**
36c9828f 10
880efa2a 11@page overview_windowids Window IDs
36c9828f 12
3863c5eb
BP
13@li @ref overview_windowids_intro
14@li @ref overview_windowids_type
15@li @ref overview_windowids_using
16
adcb6f88 17@see
3863c5eb
BP
18
19@li wxIdManager
20@li wxWindow::NewControlId
21@li wxWindow::UnreserveControlId
22
23
24<hr>
25
26
27@section overview_windowids_intro Introduction
28
29Various contols and other parts of wxWidgets need an ID. Sometimes the ID may
30be directly provided by the use or have a predefined value, such as
31@c wxID_OPEN. Often, however, the value of the ID is unimportant and is created
32automatically by calling wxWindow::NewControlId or by passing @c wxID_ANY as
33the ID of an object.
34
35There are two ways to generate an ID. One way, is to start at a negative
36number, and for each new ID, return the next smallest number. This is fine for
37systems that can used the full range of negative numbers for an ID, as this
38provides more than enough IDs and it would take a very very long time to run
39out and wrap around. However, some systems can not use the full range of the
40ID value. Windows, for example, can only use 16 bit IDs, and only has about
4132000 possible automatic IDs that can be generated by wxWindow::NewControlId.
42If the program runs long enough, depending on the program itself, using this
43first method would cause the IDs to wrap around into the positive ID range and
44cause possible clashes with any directly specified ID values.
45
46The other way is to keep track of the IDs returned by wxWindow::NewControlId
47and don't return them again until the ID is completely free and not being used
48by any other objects. This will make sure that the ID values do not clash with
49one another. This is accomplished by keeping a reference count for each of the
50IDs that can possibly be returned by wxWindow::NewControlId. Other IDs are not
51reference counted.
52
53
54@section overview_windowids_type Data Types
55
56A wxWindowID is just the integer type for a window ID. It should be used
57almost everywhere. To help keep track of the count for the automatically
58generated IDs, a new type, wxWindowIDRef exists, that can take the place of
59wxWindowID where needed. When an ID is first created, it is marked as reserved.
60When assigning it to a wxWindowIDRef, the usage count of the ID is increased,
61or set to 1 if it is currently reserved. Assigning the same ID to several
62wxWindowIDRefs will keep track of the count. As the wxWindowIDRef gets
63destroyed or its value changes, it will decrease the count of the used ID. When
64there are no more wxWindowIDRef types with the created ID, the ID is considered
65free and can then be used again by wxWindow::NewControlId.
66
67If a created ID is not assigned to a wxWindowIDRef, then it remains reserved
68until it is unreserved manually with wxWindow::UnreserveControlId. However, if
69it is assigned to a wxWindowIDRef, then it will be unreserved automatically and
70will be considered free when the count is 0, and should NOT be manually
71unreserved.
72
73wxWindowIDRef can store both automatic IDs from wxWindow::NewControlId as well
74as normal IDs. Reference counting is only done for the automatic IDs. Also,
75wxWindowIDRef has conversion operators that allow it to be treated just like a
76wxWindowID.
77
78
79@section overview_windowids_using Using wxWindowIDRef
80
81A wxWindowIDRef should be used in place of a wxWindowID where you want to make
82sure the ID is not created again by wxWindow::NewControlId at least until the
83wxWindowIDRef is destroyed, usually when the associated object is destroyed.
84This is done already for windows, menu items, and tool bar items. It should
85only be used in the main thread, as it is not thread safe.
86
87*/
36c9828f 88