Finished review of Dialogs category of functions and macros as well as choicdlg.h (assigned to myself).

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

interface/utils.h

@@ -82,11 +82,75 @@ public:
 // Global functions/macros
 // ============================================================================
 
+
+/** @ingroup group_funcmacro_dialog */
+//@{
+
+/**
+    Changes the cursor to the given cursor for all windows in the application.
+    Use wxEndBusyCursor() to revert the cursor back to its previous state.
+    These two calls can be nested, and a counter ensures that only the outer
+    calls take effect.
+
+    @see wxIsBusy(), wxBusyCursor
+
+    @header{wx/utils.h}
+*/
+void wxBeginBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR);
+
+/**
+    Changes the cursor back to the original cursor, for all windows in the
+    application. Use with wxBeginBusyCursor().
+
+    @see wxIsBusy(), wxBusyCursor
+
+    @header{wx/utils.h}
+*/
+void wxEndBusyCursor();
+
+/**
+    Returns @true if between two wxBeginBusyCursor() and wxEndBusyCursor()
+    calls.
+
+    @see wxBusyCursor.
+
+    @header{wx/utils.h}
+*/
+bool wxIsBusy();
+
+/**
+    Ring the system bell.
+
+    @note This function is categorized as a GUI one and so is not thread-safe.
+
+    @header{wx/utils.h}
+*/
+void wxBell();
+
+/**
+    Shows a message box with the information about the wxWidgets build used,
+    including its version, most important build parameters and the version of
+    the underlying GUI toolkit. This is mainly used for diagnostic purposes
+    and can be invoked by Ctrl-Alt-middle clicking on any wxWindow which
+    doesn't otherwise handle this event.
+
+    @wxsince{2.9.0}
+
+    @header{wx/utils.h}
+*/
+void wxInfoMessageBox(wxWindow parent = NULL);
+
+//@}
+
+
+
 /**
     Returns the type of power source as one of @c wxPOWER_SOCKET,
     @c wxPOWER_BATTERY or @c wxPOWER_UNKNOWN.
     @c wxPOWER_UNKNOWN is also the default on platforms where this
     feature is not implemented (currently everywhere but MS Windows).
+
+    @header{wx/utils.h}
 */
 wxPowerType wxGetPowerType();
 
@@ -103,6 +167,8 @@ wxPowerType wxGetPowerType();
     if successful, @false otherwise.
 
     @see wxGetUserName()
+
+    @header{wx/utils.h}
 */
 wxString wxGetUserId();
 bool wxGetUserId(char* buf, int sz);
@@ -114,6 +180,8 @@ bool wxGetUserId(char* buf, int sz);
     Displays @a msg and exits. This writes to standard error under Unix,
     and pops up a message box under Windows. Used for fatal internal
     wxWidgets errors. See also wxError().
+
+    @header{wx/utils.h}
 */
 void wxFatalError(const wxString& msg,
                   const wxString& title = "wxWidgets Fatal Error");
@@ -124,6 +192,8 @@ void wxFatalError(const wxString& msg,
     @c wxBATTERY_SHUTDOWN_STATE or @c wxBATTERY_UNKNOWN_STATE.
     @c wxBATTERY_UNKNOWN_STATE is also the default on platforms where
     this feature is not implemented (currently everywhere but MS Windows).
+
+    @header{wx/utils.h}
 */
 wxBatteryState wxGetBatteryState();
 
@@ -137,18 +207,12 @@ wxBatteryState wxGetBatteryState();
     window hierarchy.
     The search is recursive in both cases.
     If no such named window is found, @b wxFindWindowByLabel is called.
+
+    @header{wx/utils.h}
 */
 wxWindow* wxFindWindowByName(const wxString& name,
                              wxWindow* parent = NULL);
 
-/**
-    Changes the cursor back to the original cursor, for all windows in the
-    application.
-    Use with wxBeginBusyCursor().
-    See also wxIsBusy(), wxBusyCursor.
-*/
-void wxEndBusyCursor();
-
 /**
     This function is deprecated as the ids generated by it can conflict with the
     ids defined by the user code, use @c wxID_ANY to assign ids which are
@@ -156,12 +220,16 @@ void wxEndBusyCursor();
     items you create instead of using this function.
 
     Generates an integer identifier unique to this run of the program.
+
+    @header{wx/utils.h}
 */
 long wxNewId();
 
 /**
     Ensures that ids subsequently generated by @b NewId do not clash with
     the given @b id.
+
+    @header{wx/utils.h}
 */
 void wxRegisterId(long id);
 
@@ -178,6 +246,8 @@ void wxRegisterId(long id);
     each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s
     (at least for Watcom C++): preformat your messages and use OutputDebugString
     instead.
+
+    @header{wx/utils.h}
 */
 void wxDebugMsg(const wxString& fmt, ... );
 
@@ -188,6 +258,8 @@ void wxDebugMsg(const wxString& fmt, ... );
     currently no way to test whether togglable keys are up or down.
     Even though there are virtual key codes defined for mouse buttons, they
     cannot be used with this function currently.
+
+    @header{wx/utils.h}
 */
 bool wxGetKeyState(wxKeyCode key);
 
@@ -197,6 +269,8 @@ bool wxGetKeyState(wxKeyCode key);
     @c Windows NT Version 4.0 or @c Linux 2.2.2 i386.
 
     @see ::wxGetOsVersion
+
+    @header{wx/utils.h}
 */
 wxString wxGetOsDescription();
 
@@ -204,6 +278,8 @@ wxString wxGetOsDescription();
     Return the (current) user's home directory.
 
     @see wxGetUserHome(), wxStandardPaths
+
+    @header{wx/utils.h}
 */
 wxString wxGetHomeDir();
 
@@ -211,6 +287,8 @@ wxString wxGetHomeDir();
     Sleeps for the specified number of milliseconds. Notice that usage of this
     function is encouraged instead of calling usleep(3) directly because the
     standard usleep() function is not MT safe.
+
+    @header{wx/utils.h}
 */
 void wxMilliSleep(unsigned long milliseconds);
 
@@ -219,22 +297,16 @@ void wxMilliSleep(unsigned long milliseconds);
     not, in fact, be available on all platforms (currently only Unix platforms with
     nanosleep(2) may provide it) in which case this is the same as
     wxMilliSleep()(@e microseconds/1000).
+
+    @header{wx/utils.h}
 */
 void wxMicroSleep(unsigned long microseconds);
 
-/**
-    Shows a message box with the information about the wxWidgets build used,
-    including its version, most important build parameters and the version of the
-    underlying GUI toolkit. This is mainly used for diagnostic purposes and can be
-    invoked by Ctrl-Alt-middle clicking on any wxWindow which doesn't otherwise
-    handle this event.
-
-        @wxsince{2.9.0}
-*/
-void wxInfoMessageBox(wxWindow ( parent = NULL);
 
 /**
     Find a menu item identifier associated with the given frame's menu bar.
+
+    @header{wx/utils.h}
 */
 int wxFindMenuItemId(wxFrame* frame, const wxString& menuString,
                     const wxString& itemString);
@@ -242,6 +314,8 @@ int wxFindMenuItemId(wxFrame* frame, const wxString& menuString,
 /**
     This function enables or disables all top level windows. It is used by
     ::wxSafeYield.
+
+    @header{wx/utils.h}
 */
 void wxEnableTopLevelWindows(bool enable = true);
 
@@ -256,6 +330,8 @@ void wxEnableTopLevelWindows(bool enable = true);
     Notice that in most cases
     wxMenuItem::GetLabelFromText or
     wxControl::GetLabelText can be used instead.
+
+    @header{wx/utils.h}
 */
 wxString wxStripMenuCodes(const wxString& str,
                             int flags = wxStrip_All);
@@ -266,6 +342,8 @@ wxString wxStripMenuCodes(const wxString& str,
     Displays @a msg and continues. This writes to standard error under
     Unix, and pops up a message box under Windows. Used for internal
     wxWidgets errors. See also wxFatalError().
+
+    @header{wx/utils.h}
 */
 void wxError(const wxString& msg,
             const wxString& title = "wxWidgets Internal Error");
@@ -282,6 +360,8 @@ void wxError(const wxString& msg,
     is launched to open the given URL may be URL-dependent (e.g. a browser may be
     used for
     local URLs while another one may be used for remote URLs).
+
+    @header{wx/utils.h}
 */
 bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0);
 
@@ -289,6 +369,8 @@ bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0);
     Executes a command in an interactive shell window. If no command is
     specified, then just the shell is spawned.
     See also wxExecute(), @ref overview_sampleexec "Exec sample".
+
+    @header{wx/utils.h}
 */
 bool wxShell(const wxString& command = NULL);
 
@@ -297,6 +379,8 @@ bool wxShell(const wxString& command = NULL);
     See wxPlatformInfo for more details about wxOperatingSystemId.
 
     @see ::wxGetOsDescription, wxPlatformInfo
+
+    @header{wx/utils.h}
 */
 wxOperatingSystemId wxGetOsVersion(int* major = NULL,
                                     int* minor = NULL);
@@ -306,24 +390,19 @@ wxOperatingSystemId wxGetOsVersion(int* major = NULL,
     error.
 
     @see wxGetHostName()
+
+    @header{wx/utils.h}
 */
 wxString wxGetFullHostName();
 
-/**
-    Changes the cursor to the given cursor for all windows in the application.
-    Use wxEndBusyCursor() to revert the cursor back
-    to its previous state. These two calls can be nested, and a counter
-    ensures that only the outer calls take effect.
-    See also wxIsBusy(), wxBusyCursor.
-*/
-void wxBeginBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR);
-
 /**
     Tells the system to delete the specified object when
     all other events have been processed. In some environments, it is
     necessary to use this instead of deleting a frame directly with the
     delete operator, because some GUIs will still send events to a deleted window.
     Now obsolete: use wxWindow::Close instead.
+
+    @header{wx/utils.h}
 */
 void wxPostDelete(wxObject* object);
 
@@ -337,6 +416,8 @@ void wxPostDelete(wxObject* object);
     frames and dialog boxes; if non-@NULL, the search will be limited to the given
     window hierarchy.
     The search is recursive in both cases.
+
+    @header{wx/utils.h}
 */
 wxWindow* wxFindWindowByLabel(const wxString& label,
                                 wxWindow* parent = NULL);
@@ -344,6 +425,8 @@ wxWindow* wxFindWindowByLabel(const wxString& label,
 
 /**
     Returns the mouse position in screen coordinates.
+
+    @header{wx/utils.h}
 */
 wxPoint wxGetMousePosition();
 
@@ -360,6 +443,8 @@ wxPoint wxGetMousePosition();
 
     where @c file.ext is a file that the resource compiler can find.
     This function is available under Windows only.
+
+    @header{wx/utils.h}
 */
 wxString wxLoadUserResource(const wxString& resourceName,
                             const wxString& resourceType = "TEXT");
@@ -376,6 +461,8 @@ wxMemorySize wxGetFreeMemory();
     Note that under Win32 it may not return correct value for the variables set
     with wxSetEnv(), use wxGetEnv() function
     instead.
+
+    @header{wx/utils.h}
 */
 wxChar* wxGetEnv(const wxString& var);
 
@@ -392,6 +479,8 @@ wxChar* wxGetEnv(const wxString& var);
     if successful, @false otherwise.
 
     @see wxGetFullHostName()
+
+    @header{wx/utils.h}
 */
 wxString wxGetHostName();
 bool wxGetHostName(char* buf, int sz);
@@ -402,26 +491,26 @@ bool wxGetHostName(char* buf, int sz);
     @a value may be @NULL if you just want to know if the variable exists
     and are not interested in its value.
     Returns @true if the variable exists, @false otherwise.
+
+    @header{wx/utils.h}
 */
 bool wxGetEnv(const wxString& var, wxString* value);
 
 /**
     Under X only, returns the current display name. See also wxSetDisplayName().
+
+    @header{wx/utils.h}
 */
 wxString wxGetDisplayName();
 
-/**
-    Ring the system bell.
-    Note that this function is categorized as a GUI one and so is not thread-safe.
-*/
-void wxBell();
-
 /**
     Returns the home directory for the given user. If the @a user is empty
     (default value), this function behaves like
     wxGetHomeDir() i.e. returns the current user home
     directory.
     If the home directory couldn't be determined, an empty string is returned.
+
+    @header{wx/utils.h}
 */
 wxString wxGetUserHome(const wxString& user = "");
 
@@ -500,6 +589,8 @@ wxString wxGetUserHome(const wxString& user = "");
         An optional pointer to wxProcess
 
     @see wxShell(), wxProcess, @ref overview_sampleexec "Exec sample".
+
+    @header{wx/utils.h}
 */
 long wxExecute(const wxString& command, int sync = wxEXEC_ASYNC,
                 wxProcess* callback = NULL);
@@ -517,6 +608,8 @@ wxPerl note: long wxExecute(const wxString& command,
 
 /**
     Returns a string representing the current date and time.
+
+    @header{wx/utils.h}
 */
 wxString wxNow();
 
@@ -531,12 +624,16 @@ wxString wxNow();
     fact
     that there isn't always a standard way to do a reliable check on the OS
     architecture.
+
+    @header{wx/utils.h}
 */
 bool wxIsPlatform64Bit();
 
 /**
     Returns the number uniquely identifying the current process in the system.
     If an error occurs, 0 is returned.
+
+    @header{wx/utils.h}
 */
 unsigned long wxGetProcessId();
 
@@ -590,6 +687,8 @@ unsigned long wxGetProcessId();
     to wxExecute.
 
     @see wxProcess::Kill, wxProcess::Exists, @ref overview_sampleexec "Exec sample"
+
+    @header{wx/utils.h}
 */
 int wxKill(long pid, int sig = wxSIGTERM, wxKillError rc = NULL,
             int flags = 0);
@@ -599,22 +698,19 @@ int wxKill(long pid, int sig = wxSIGTERM, wxKillError rc = NULL,
     instance that contains the current position of the mouse pointer in
     screen coordinates, as well as boolean values indicating the up/down
     status of the mouse buttons and the modifier keys.
+
+    @header{wx/utils.h}
 */
 wxMouseState wxGetMouseState();
 
-/**
-    Returns @true if between two wxBeginBusyCursor() and
-    wxEndBusyCursor() calls.
-    See also wxBusyCursor.
-*/
-bool wxIsBusy();
-
 //@{
 /**
     Copies the user's email address into the supplied buffer, by
     concatenating the values returned by wxGetFullHostName()
     and wxGetUserId().
     Returns @true if successful, @false otherwise.
+
+    @header{wx/utils.h}
 */
 wxString wxGetEmailAddress();
 bool wxGetEmailAddress(char* buf, int sz);
@@ -622,6 +718,8 @@ bool wxGetEmailAddress(char* buf, int sz);
 
 /**
     Sleeps for the specified number of seconds.
+
+    @header{wx/utils.h}
 */
 void wxSleep(int secs);
 
@@ -631,6 +729,8 @@ void wxSleep(int secs);
     Returns @true on success.
 
     @see wxUnsetEnv()
+
+    @header{wx/utils.h}
 */
 bool wxSetEnv(const wxString& var, const wxString& value);
 
@@ -640,6 +740,8 @@ bool wxSetEnv(const wxString& var, const wxString& value);
     The check is performed at run-time.
 
     @see @ref overview_byteordermacros "Byte order macros"
+
+    @header{wx/utils.h}
 */
 bool wxIsPlatformLittleEndian();
 
@@ -652,6 +754,8 @@ bool wxIsPlatformLittleEndian();
     multiple
     displays to be used.
     See also wxGetDisplayName().
+
+    @header{wx/utils.h}
 */
 void wxSetDisplayName(const wxString& displayName);