docs/doxygen/overviews/windowids.h

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