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

diff --git a/docs/latex/wx/idmanager.tex b/docs/latex/wx/idmanager.tex
index 5d45630fd36b2792950b3615b993b25c49eec8a2..9b73020185ace61411ac765dafd37d5bf11ea0ba 100644 (file)
--- 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 (file)
index 0000000..19287a2
--- /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 fb3be836e0dbc27765c75ac59ed19395c2197147..d7796285d0d31981cf0c7ddf16a35f82868b424a 100644 (file)
--- 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}