From b8c8cb27700a2ec30cc5038bc2294799fe3e1736 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Fri, 13 Nov 2015 20:41:27 +0100 Subject: [PATCH] Correct and simplify window IDs overview in the manual Explicitly mention that IDs effectively used when wxID_ANY is specified as well as IDs returned by NewControlId() are negative and that the user IDs should be positive to avoid clashing with such auto-generated ones. --- docs/doxygen/overviews/windowids.h | 29 +++++++++-------------------- 1 file changed, 9 insertions(+), 20 deletions(-) diff --git a/docs/doxygen/overviews/windowids.h b/docs/doxygen/overviews/windowids.h index 427b050c4c..a4a612cf7a 100644 --- a/docs/doxygen/overviews/windowids.h +++ b/docs/doxygen/overviews/windowids.h @@ -13,27 +13,16 @@ 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. +@c wxID_OPEN. Often, however, the value of the ID is unimportant and in this +case it is enough to use @c wxID_ANY as the ID of an object which tells +wxWidgets to assign an ID automatically. All such automatically-assigned IDs +are negative, so the IDs predefined in the user code should always be positive +to avoid clashes with them. -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. +If you do care about the ID value but don't want to specify it as a literal in +your code, you can use wxWindow::NewControlId() to create an ID that had never +been returned by this function before and, being also negative, never conflicts +with any IDs explicitly defined in the program if the advice above is followed. @see wxIdManager, wxWindow::NewControlId(), wxWindow::UnreserveControlId()