documentation for window ids allocation and wxIdManager (patch 1870570)

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@51235 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/classes.tex

@@ -236,6 +236,7 @@
 \input iconloc.tex
 \input iconevt.tex
 \input idleevt.tex
+\input idmanager.tex
 \input image.tex
 \input imaglist.tex
 \input ilayout.tex

docs/latex/wx/idmanager.tex

@@ -0,0 +1,64 @@
+\section{\class{wxIdManager}}\label{wxidmanager}
+
+wxIdManager is responsible for allocating and releasing window IDs.  It
+is used by \helpref{wxWindow::NewControlId}{wxwindownewcontrolid} and
+\helpref{wxWindow::UnreserveControlId}{wxwindowunreservecontrolid}, and can also
+be used be used directly.
+
+\wxheading{Derived from}
+
+No base class
+
+\wxheading{Include files}
+
+<wx/windowid.h> included from defs.h
+
+\wxheading{Library}
+
+\helpref{wxCore}{librarieslist}
+
+\wxheading{See also}
+
+\helpref{wxWindow::NewControlId}{wxwindownewcontrolid}
+\helpref{wxWindow::UnreserveControlId}{wxwindowunreservecontrolid}
+\helpref{Window IDs overview}{windowidsoverview}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxIdManager::ReserveControlId}\label{wxidmanagerreservecontrolid}
+
+\func{static wxWindowID}{ReserveControlId}{\param{int}{ count = 1}}
+
+Called directly by \helpref{wxWindow::NewControlId}{wxwindownewcontrolid},
+this function will create a new ID or range of IDs.  The IDs will be
+reserved until assigned to a \helpref{wxWindowIDRef}{windowidsoverview}
+or unreserved with \helpref{UnreserveControlId}{wxidmanagerunreservecontrolid}.
+Only ID values that are not assigned to a \helpref{wxWindowIDRef}{windowidsoverview}
+need to be unreserved.
+
+\wxheading{Parameters}
+
+\docparam{count}{The number of sequential IDs to reserve.}
+
+\wxheading{Return value}
+
+The value of the first ID in the sequence, or wxID_NONE.
+
+\membersection{wxIdManager::UnreserveControlId}\label{wxidmanagerunreservecontrolid}
+
+\func{static wxWindowID}{UnreserveControlId}{\param{wxWindowID}{ id}, \param{int}{ count = 1}}
+
+Called directly by \helpref{wxWindow::UnreserveControlId}{wxwindowunreservecontrolid},
+this function will unreserve an ID or range of IDs that is currently reserved.  This
+should only be called for IDs returned by \helpref{ReserveControlId}{wxidmanagerreservecontrolid}
+that have NOT been assigned to a \helpref{wxWindowIDRef}{windowidsoverview}
+
+\wxheading{Parameters}
+
+\docparam{id}{The first of the range of IDs to unreserve.}
+
+\docparam{count}{The number of sequential IDs to unreserve.}
+
+\wxheading{Return value}
+
+The value of the first ID in the sequence, or wxID_NONE.

docs/latex/wx/topics.tex

@@ -29,6 +29,7 @@ This chapter contains a selection of topic overviews.
 \helpref{C++ exceptions overview}{exceptionsoverview}\\
 \helpref{Window styles}{windowstyles}\\
 \helpref{Window deletion overview}{windowdeletionoverview}\\
+\helpref{Window IDs overview}{windowidsoverview}\\
 \helpref{Environment variables}{envvars}
 
 {\large {\bf Overviews of non-GUI classes}}

docs/latex/wx/topics2.tex

@@ -45,6 +45,7 @@
 \input tbook.tex
 \input tcommdlg.tex
 \input tdocview.tex
+\input twindowid.tex
 % Deprecated
 %\input ttab.tex
 \input ttoolbar.tex
@@ -63,3 +64,4 @@
 \input re_syntax.tex
 \input arc.tex
 \input backwardcompat.tex
+

docs/latex/wx/window.tex

@@ -1934,20 +1934,30 @@ Performs a keyboard navigation action inside this window.
 See \helpref{Navigate}{wxwindownavigate} for more information.
 
 
-\membersection{wxWindow::NextControlId}\label{wxwindownextcontrolid}
+\membersection{wxWindow::NewControlId}\label{wxwindownewcontrolid}
 
-\func{static int}{NextControlId}{\param{int }{winid}}
+\func{static wxWindowID}{NewControlId}{\param{int}{ count = 1}}
 
-If two controls are created consecutively using \texttt{wxID\_ANY} id, this
+Create a new ID or range of IDs that are not currently in use.  The
-function allows to retrieve the effective id of the latter control from the id
+IDs will be reserved until assigned to a \helpref{wxWindowIDRef}{windowidsoverview}
-of the former. This is useful for example to find the control following its 
+or unreserved with \helpref{UnreserveControlId}{wxwindowunreservecontrolid}.
-\helpref{wxStaticText}{wxstatictext} label if only the id of or pointer to the
+
-label is available to the caller but it is known that the two controls were
+See \helpref{Window IDs overview}{windowidsoverview} for more information.
-created together.
+
+\wxheading{Parameters}
+
+\docparam{count}{The number of sequential IDs to reserve.}
+
+\wxheading{Return value}
+
+Returns the ID or the first ID of the range, or wxID_NONE if enough
+free IDs were not available.
 
 \wxheading{See also}
 
-\helpref{PrevControlId}{wxwindowprevcontrolid}
+\helpref{UnreserveControlId}{wxwindowunreservecontrolid}
+\helpref{wxIdManager}{wxidmanager}
+\helpref{Window IDs overview}{windowidsoverview}
 
 
 %% VZ: wxWindow::OnXXX() functions should not be documented but I'm leaving
@@ -2508,15 +2518,6 @@ implements the following methods:\par
 \end{twocollist}}
 }
 
-
-\membersection{wxWindow::PrevControlId}\label{wxwindowprevcontrolid}
-
-\func{static int}{PrevControlId}{\param{int }{winid}}
-
-This is similar to \helpref{NextControlId}{wxwindownextcontrolid} but returns
-the id of the control created just before the one with the given \arg{winid}.
-
-
 \membersection{wxWindow::PushEventHandler}\label{wxwindowpusheventhandler}
 
 \func{void}{PushEventHandler}{\param{wxEvtHandler* }{handler}}
@@ -3897,6 +3898,25 @@ This function is currently only implemented under MSW.
 
 \helpref{wxWindow::RegisterHotKey}{wxwindowregisterhotkey}
 
+\membersection{wxWindow::UnreserveControlId}\label{wxwindowunreservecontrolid}
+
+\func{static void}{UnreserveControlId}{\param{wxWindowID}{ id}, \param{int}{ count = 1}}
+
+Unreserve an ID or range of IDs that was reserved by \helpref{NewControlId}{wxwindownewcontrolid}.
+
+See \helpref{Window IDs overview}{windowidsoverview} for more information.
+
+\wxheading{Parameters}
+
+\docparam{id}{The starting ID of the range of IDs to unreserve.}
+
+\docparam{count}{The number of sequential IDs to unreserve.}
+
+\wxheading{See also}
+
+\helpref{NewControlId}{wxwindownewcontrolid}
+\helpref{wxIdManager}{wxidmanager}
+\helpref{Window IDs overview}{windowidsoverview}
 
 \membersection{wxWindow::Update}\label{wxwindowupdate}