From 12ec9c090cd538db3b49904c52ce5bd9069adf84 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Wed, 16 Jan 2008 19:24:38 +0000 Subject: [PATCH] add forgotten twindowid.tex and correct LaTeX errors introduced by last commit git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@51253 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/latex/wx/idmanager.tex | 4 +-- docs/latex/wx/twindowid.tex | 63 +++++++++++++++++++++++++++++++++++++ docs/latex/wx/window.tex | 4 +-- 3 files changed, 67 insertions(+), 4 deletions(-) create mode 100644 docs/latex/wx/twindowid.tex diff --git a/docs/latex/wx/idmanager.tex b/docs/latex/wx/idmanager.tex index 5d45630fd3..9b73020185 100644 --- a/docs/latex/wx/idmanager.tex +++ b/docs/latex/wx/idmanager.tex @@ -42,7 +42,7 @@ need to be unreserved. \wxheading{Return value} -The value of the first ID in the sequence, or wxID_NONE. +The value of the first ID in the sequence, or \texttt{wxID\_NONE}. \membersection{wxIdManager::UnreserveControlId}\label{wxidmanagerunreservecontrolid} @@ -61,4 +61,4 @@ that have NOT been assigned to a \helpref{wxWindowIDRef}{windowidsoverview} \wxheading{Return value} -The value of the first ID in the sequence, or wxID_NONE. +The value of the first ID in the sequence, or \texttt{wxID\_NONE}. diff --git a/docs/latex/wx/twindowid.tex b/docs/latex/wx/twindowid.tex new file mode 100644 index 0000000000..19287a2af2 --- /dev/null +++ b/docs/latex/wx/twindowid.tex @@ -0,0 +1,63 @@ +\section{Window IDs overview}\label{windowidsoverview} + +\wxheading{See Also} + +\helpref{wxIdManager}{wxidmanager} +\helpref{wxWindow::NewControlId}{wxwindownewcontrolid} +\helpref{wxWindow::UnreserveControlId}{wxwindowunreservecontrolid} + +\subsection{Introduction}\label{windowidsoverviewintro} + +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 +wxID_OPEN. Often, however, the value of the ID is unimportant and is created +automatically by calling \helpref{wxWindow::NewControlId}{wxwindownewcontrolid} +or by passing 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 \helpref{wxWindow::NewControlId}{wxwindownewcontrolid}. +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 \helpref{wxWindow::NewControlId}{wxwindownewcontrolid} +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 \helpref{wxWindow::NewControlId}{wxwindownewcontrolid}. +Other IDs are not reference counted. + +\subsection{Data types}\label{windowidsoverviewtypes} + +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 \helpref{wxWindow::NewControlId}{wxwindownewcontrolid}. + +If a created ID is not assigned to a wxWindowIDRef, then it remains reserved until it +is unreserved manually with \helpref{wxWindow::UnreserveControlId}{wxwindowunreservecontrolid}. +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 \helpref{wxWindow::NewControlId}{wxwindownewcontrolid} +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. + +\subsection{Using wxWindowIDRef}\label{windowidsoverviewusing} + +A wxWindowIDRef should be used in place of a wxWindowID where you want to make sure the +ID is not created again by \helpref{wxWindow::NewControlId}{wxwindownewcontrolid} +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. + diff --git a/docs/latex/wx/window.tex b/docs/latex/wx/window.tex index fb3be836e0..d7796285d0 100644 --- a/docs/latex/wx/window.tex +++ b/docs/latex/wx/window.tex @@ -1950,8 +1950,8 @@ See \helpref{Window IDs overview}{windowidsoverview} for more information. \wxheading{Return value} -Returns the ID or the first ID of the range, or wxID_NONE if enough -free IDs were not available. +Returns the ID or the first ID of the range, or \texttt{wxID\_NONE} if the +specified number of identifiers couldn't be allocated. \wxheading{See also} -- 2.45.2