docs/doxygen/overviews/windowids.h

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