Mention graphics device classes

[wxWidgets.git] / interface / utils.h

diff --git a/interface/utils.h b/interface/utils.h
index e6337c5f9efae39da1f41b813ba3f2222b12e1b9..357d2822329ebd2214e66dcc8c7b0a91bdaf3f3d 100644 (file)
--- a/interface/utils.h
+++ b/interface/utils.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        utils.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        utils.h

-// Purpose:     interface of wxWindowDisabler
+// Purpose:     interface of various utility classes and functions

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license


@@ -10,14 +10,15 @@
     @class wxWindowDisabler
     @wxheader{utils.h}
 
     @class wxWindowDisabler
     @wxheader{utils.h}
 

-    This class disables all windows of the application (may be with the exception
-    of one of them) in its constructor and enables them back in its destructor.
+    This class disables all windows of the application (may be with the
+    exception of one of them) in its constructor and enables them back in its
+    destructor.

 
     This is useful when you want to indicate to the user that the application
     is currently busy and cannot respond to user input.
 
     @library{wxcore}
 
     This is useful when you want to indicate to the user that the application
     is currently busy and cannot respond to user input.
 
     @library{wxcore}

-    @category{FIXME}
+    @category{misc}

 
     @see wxBusyCursor
 */
 
     @see wxBusyCursor
 */


@@ -35,13 +36,13 @@ public:
     wxWindowDisabler(bool disable = true);
 
     /**
     wxWindowDisabler(bool disable = true);
 
     /**

-        Disables all top level windows of the applications with the exception of
-        @a winToSkip if it is not @NULL.
+        Disables all top level windows of the applications with the exception
+        of @a winToSkip if it is not @NULL.

     */
     wxWindowDisabler(wxWindow* winToSkip);
 
     /**
     */
     wxWindowDisabler(wxWindow* winToSkip);
 
     /**

-        Reenables back the windows disabled by the constructor.
+        Reenables the windows disabled by the constructor.

     */
     ~wxWindowDisabler();
 };
     */
     ~wxWindowDisabler();
 };


@@ -52,24 +53,24 @@ public:
     @class wxBusyCursor
     @wxheader{utils.h}
 
     @class wxBusyCursor
     @wxheader{utils.h}
 

-    This class makes it easy to tell your user that the program is temporarily busy.
-    Just create a wxBusyCursor object on the stack, and within the current scope,
-    the hourglass will be shown.
+    This class makes it easy to tell your user that the program is temporarily
+    busy. Just create a wxBusyCursor object on the stack, and within the
+    current scope, the hourglass will be shown.

 
     For example:
 
     @code
     wxBusyCursor wait;
 
 
     For example:
 
     @code
     wxBusyCursor wait;
 

-      for (int i = 0; i  100000; i++)
+    for (int i = 0; i < 100000; i++)

         DoACalculation();
     @endcode
 
         DoACalculation();
     @endcode
 

-    It works by calling wxBeginBusyCursor() in the constructor,
-    and wxEndBusyCursor() in the destructor.
+    It works by calling wxBeginBusyCursor() in the constructor, and
+    wxEndBusyCursor() in the destructor.

 
     @library{wxcore}
 
     @library{wxcore}

-    @category{FIXME}
+    @category{misc}

 
     @see wxBeginBusyCursor(), wxEndBusyCursor(), wxWindowDisabler
 */
 
     @see wxBeginBusyCursor(), wxEndBusyCursor(), wxWindowDisabler
 */


@@ -89,6 +90,87 @@ public:
 
 
 
 
 
 

+/**
+    @class wxMouseState
+    @wxheader{utils.h}
+
+    Represents the mouse state.
+
+    The methods of this class generally mirror the corresponding methods of
+    wxMouseEvent.
+
+    This class is implemented entirely in @<wx/utils.h@>, meaning no extra
+    library needs to be linked to use this class.
+
+    @category{misc}
+
+    @see wxGetMouseState()
+ */
+class wxMouseState
+{
+public:
+    /**
+        Default constructor.
+    */
+    wxMouseState();
+
+    /**
+        Returns X coordinate of the physical mouse event position.
+    */
+    wxCoord GetX() const;
+    /**
+        Returns Y coordinate of the physical mouse event position.
+    */
+    wxCoord GetY() const;
+    /**
+        Returns the physical mouse position.
+    */
+    wxPoint GetPosition() const;
+
+    /**
+        Returns @true if the left mouse button changed to down.
+    */
+    bool LeftDown() const;
+    /**
+        Returns @true if the middle mouse button changed to down.
+    */
+    bool MiddleDown() const;
+    /**
+        Returns @true if the right mouse button changed to down.
+    */
+    bool RightDown() const;
+    /**
+        Returns @true if the first extra button mouse button changed to down.
+    */
+    bool Aux1Down() const;
+    /**
+        Returns @true if the second extra button mouse button changed to down.
+    */
+    bool Aux2Down() const;
+
+    /**
+        Returns @true if the control key is down.
+    */
+    bool ControlDown() const;
+    /**
+        Returns @true if the shift key is down.
+    */
+    bool ShiftDown() const;
+    /**
+        Returns @true if the alt key is down.
+    */
+    bool AltDown() const;
+    /**
+        Returns @true if the meta key is down.
+    */
+    bool MetaDown() const;
+    /**
+        Same as MetaDown() under Mac systems, ControlDown() for the others.
+    */
+    bool CmdDown() const;
+};
+
+

 // ============================================================================
 // Global functions/macros
 // ============================================================================
 // ============================================================================
 // Global functions/macros
 // ============================================================================


@@ -145,7 +227,7 @@ void wxBell();
     and can be invoked by Ctrl-Alt-middle clicking on any wxWindow which
     doesn't otherwise handle this event.
 
     and can be invoked by Ctrl-Alt-middle clicking on any wxWindow which
     doesn't otherwise handle this event.
 

-    @wxsince{2.9.0}
+    @since 2.9.0

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */


@@ -206,127 +288,127 @@ bool wxUnsetEnv(const wxString& var);
 
 
 
 
 
 

-/** @ingroup group_funcmacro_log */
+/** @ingroup group_funcmacro_misc */

 //@{
 
 /**
 //@{
 
 /**

-    @deprecated Replaced by wxLogDebug().
-
-    Displays a debugging message. Under Windows, this will appear on the
-    debugger command window, and under Unix, it will be written to standard
-    error.
+    Returns battery state as one of @c wxBATTERY_NORMAL_STATE,
+    @c wxBATTERY_LOW_STATE, @c wxBATTERY_CRITICAL_STATE,
+    @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).

 
 

-    The syntax is identical to @e printf(), pass a format string and a variable
-    list of arguments.
+    @header{wx/utils.h}
+*/
+wxBatteryState wxGetBatteryState();

 
 

-    @note Under Windows, if your application crashes before the message appears
-          in the debugging window, put a wxYield() call after each wxDebugMsg()
-          call. wxDebugMsg() seems to be broken under WIN32s (at least for
-          Watcom C++): preformat your messages and use OutputDebugString
-          instead.
+/**
+    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}
 */
 
     @header{wx/utils.h}
 */

-void wxDebugMsg(const wxString& format, ... );
+wxPowerType wxGetPowerType();

 
 /**
 
 /**

-    @deprecated Replaced by wxLogFatalError().
+    Under X only, returns the current display name.

 
 

-    Displays @a message and exits. This writes to standard error under Unix,
-    and pops up a message box under Windows. Used for fatal internal wxWidgets
-    errors.
-
-    @eee wxError()
+    @see wxSetDisplayName()

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-void wxFatalError(const wxString& message,
-                   const wxString& title = "wxWidgets Fatal Error");
+wxString wxGetDisplayName();

 
 /**
 
 /**

-    @deprecated Replaced by wxLogError().
+    For normal keys, returns @true if the specified key is currently down.

 
 

-    Displays @a message and continues. This writes to standard error under
-    Unix, and pops up a message box under Windows. Used for internal wxWidgets
-    errors.
+    For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns @true if
+    the key is toggled such that its LED indicator is lit. There is currently
+    no way to test whether togglable keys are up or down.

 
 

-    @see wxFatalError()
+    Even though there are virtual key codes defined for mouse buttons, they
+    cannot be used with this function currently.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-void wxError(const wxString& message,
-              const wxString& title = "wxWidgets Internal Error");
-
-//@}
-
-
+bool wxGetKeyState(wxKeyCode key);

 
 /**
 
 /**

-    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).
+    Returns the mouse position in screen coordinates.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxPowerType wxGetPowerType();
+wxPoint wxGetMousePosition();

 
 /**
 
 /**

-    This function returns the "user id" also known as "login name" under Unix
-    i.e.  something like "jsmith". It uniquely identifies the current user (on
-    this system).  Under Windows or NT, this function first looks in the
-    environment variables USER and LOGNAME; if neither of these is found, the
-    entry @b UserId in the @b wxWidgets section of the WIN.INI file is tried.
+    Returns the current state of the mouse.  Returns a wxMouseState 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.

 
 

-    @return Returns the login name if successful or an empty string otherwise.
+    @header{wx/utils.h}
+*/
+wxMouseState wxGetMouseState();

 
 

-    @see wxGetUserName()
+/**
+    This function enables or disables all top level windows. It is used by
+    wxSafeYield().

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxString wxGetUserId();
+void wxEnableTopLevelWindows(bool enable = true);

 
 /**
 
 /**

-    @deprecated
-    This form is deprecated, use wxGetUserId() version that returns wxString.
+    Find the deepest window at the given mouse position in screen coordinates,
+    returning the window if found, or @NULL if not.

 
 

-    @param buf Buffer to store login name in.
-    @param sz  Size of the buffer.
-
-    @return Returns @true if successful, @false otherwise.
- */
-bool wxGetUserId(char* buf, int sz);
+    @header{wx/utils.h}
+*/
+wxWindow* wxFindWindowAtPoint(const wxPoint& pt);

 
 /**
 
 /**

-    Returns battery state as one of @c wxBATTERY_NORMAL_STATE,
-    @c wxBATTERY_LOW_STATE, @c wxBATTERY_CRITICAL_STATE,
-    @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).
+    @deprecated Replaced by wxWindow::FindWindowByLabel().
+
+    Find a window by its label. Depending on the type of window, the label may
+    be a window title or panel item label. If @a parent is @NULL, the search
+    will start from all top-level 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}
 */
 
     @header{wx/utils.h}
 */

-wxBatteryState wxGetBatteryState();
+wxWindow* wxFindWindowByLabel(const wxString& label,
+                              wxWindow* parent = NULL);

 
 /**
 
 /**

-    @deprecated
-    This function is obsolete, please use wxWindow::FindWindowByName() instead.
+    @deprecated Replaced by wxWindow::FindWindowByName().

 
 

-    Find a window by its name (as given in a window constructor or Create()
-    function call).  If @a parent is @NULL, the search will start from all
+    Find a window by its name (as given in a window constructor or @e Create
+    function call). If @a parent is @NULL, the search will start from all

     top-level frames and dialog boxes; if non-@NULL, the search will be limited
     top-level frames and dialog boxes; if non-@NULL, the search will be limited

-    to the given window hierarchy.  The search is recursive in both cases.  If
-    no such named window is found, wxFindWindowByLabel() is called.
+    to the given window hierarchy. The search is recursive in both cases.
+
+    If no such named window is found, wxFindWindowByLabel() is called.

 
     @header{wx/utils.h}
 */
 wxWindow* wxFindWindowByName(const wxString& name, wxWindow* parent = NULL);
 
 /**
 
     @header{wx/utils.h}
 */
 wxWindow* wxFindWindowByName(const wxString& name, wxWindow* parent = NULL);
 
 /**

-    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
-    guaranteed to not conflict with the user-defined ids for the controls and menu
-    items you create instead of using this function.
+    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);
+
+/**
+    @deprecated Ids generated by it can conflict with the Ids defined by the
+                user code, use @c wxID_ANY to assign ids which are guaranteed
+                to not conflict with the user-defined ids for the controls and
+                menu items you create instead of using this function.

 
     Generates an integer identifier unique to this run of the program.
 
 
     Generates an integer identifier unique to this run of the program.
 


@@ -335,134 +417,167 @@ wxWindow* wxFindWindowByName(const wxString& name, wxWindow* parent = NULL);
 long wxNewId();
 
 /**
 long wxNewId();
 
 /**

-    Ensures that ids subsequently generated by @b NewId do not clash with
-    the given @b id.
+    Ensures that Ids subsequently generated by wxNewId() do not clash with the
+    given @a id.

 
     @header{wx/utils.h}
 */
 void wxRegisterId(long id);
 
 /**
 
     @header{wx/utils.h}
 */
 void wxRegisterId(long id);
 
 /**

-    For normal keys, returns @true if the specified key is currently down.
-    For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns
-    @true if the key is toggled such that its LED indicator is lit. There is
-    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.
+    Opens the @a url in user's default browser. If the @a flags parameter
+    contains @c wxBROWSER_NEW_WINDOW flag, a new window is opened for the URL
+    (currently this is only supported under Windows). The @a url may also be a
+    local file path (with or without the "file://" prefix), if it doesn't
+    correspond to an existing file and the URL has no scheme "http://" is
+    prepended to it by default.
+
+    Returns @true if the application was successfully launched.
+
+    @note For some configurations of the running user, the application which 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}
 */
 
     @header{wx/utils.h}
 */

-bool wxGetKeyState(wxKeyCode key);
+bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0);

 
 /**
 
 /**

-    Returns the string containing the description of the current platform in a
-    user-readable form. For example, this function may return strings like
-    @c Windows NT Version 4.0 or @c Linux 2.2.2 i386.
+    Loads a user-defined Windows resource as a string. If the resource is
+    found, the function creates a new character array and copies the data into
+    it. A pointer to this data is returned. If unsuccessful, @NULL is returned.

 
 

-    @see ::wxGetOsVersion
+    The resource must be defined in the @c .rc file using the following syntax:
+
+    @code
+    myResource TEXT file.ext
+    @endcode
+
+    Where @c file.ext is a file that the resource compiler can find.
+
+    This function is available under Windows only.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxString wxGetOsDescription();
+wxString wxLoadUserResource(const wxString& resourceName,
+                            const wxString& resourceType = "TEXT");

 
 /**
 
 /**

-    Return the (current) user's home directory.
+    @deprecated Replaced by wxWindow::Close(). See the
+                @ref overview_windowdeletion "window deletion overview".

 
 

-    @see wxGetUserHome(), wxStandardPaths
+    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.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxString wxGetHomeDir();
+void wxPostDelete(wxObject* object);

 
 /**
 
 /**

-    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.
+    Under X only, sets the current display name. This is the X host and display
+    name such as "colonsay:0.0", and the function indicates which display
+    should be used for creating windows from this point on. Setting the display
+    within an application allows multiple displays to be used.
+
+    @see wxGetDisplayName()

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-void wxMilliSleep(unsigned long milliseconds);
+void wxSetDisplayName(const wxString& displayName);

 
 /**
 
 /**

-    Sleeps for the specified number of microseconds. The microsecond resolution may
-    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).
+    Strips any menu codes from @a str and returns the result.
+
+    By default, the functions strips both the mnemonics character (@c '&')
+    which is used to indicate a keyboard shortkey, and the accelerators, which
+    are used only in the menu items and are separated from the main text by the
+    @c \t (TAB) character. By using @a flags of @c wxStrip_Mnemonics or
+    @c wxStrip_Accel to strip only the former or the latter part, respectively.
+
+    Notice that in most cases wxMenuItem::GetLabelFromText() or
+    wxControl::GetLabelText() can be used instead.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-void wxMicroSleep(unsigned long microseconds);
+wxString wxStripMenuCodes(const wxString& str, int flags = wxStrip_All);
+
+//@}
+

 
 
 
 

+/** @ingroup group_funcmacro_networkuseros */
+//@{
+

 /**
 /**

-    Find a menu item identifier associated with the given frame's menu bar.
+    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}
 */
 
     @header{wx/utils.h}
 */

-int wxFindMenuItemId(wxFrame* frame, const wxString& menuString,
-                    const wxString& itemString);
+wxString wxGetEmailAddress();

 
 /**
 
 /**

-    This function enables or disables all top level windows. It is used by
-    ::wxSafeYield.
+    @deprecated Use wxGetEmailAddress() instead.
+
+    @param buf Buffer to store the email address in.
+    @param sz  Size of the buffer.
+
+    @returns @true if successful, @false otherwise.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-void wxEnableTopLevelWindows(bool enable = true);
+bool wxGetEmailAddress(char* buf, int sz);

 
 /**
 
 /**

-    Strips any menu codes from @a str and returns the result.
-    By default, the functions strips both the mnemonics character (@c '')
-    which is used to indicate a keyboard shortkey, and the accelerators, which are
-    used only in the menu items and are separated from the main text by the
-    @c \t (TAB) character. By using @a flags of
-    @c wxStrip_Mnemonics or @c wxStrip_Accel to strip only the former
-    or the latter part, respectively.
-    Notice that in most cases
-    wxMenuItem::GetLabelFromText or
-    wxControl::GetLabelText can be used instead.
+    Returns the amount of free memory in bytes under environments which support
+    it, and -1 if not supported or failed to perform measurement.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxString wxStripMenuCodes(const wxString& str,
-                            int flags = wxStrip_All);
+wxMemorySize wxGetFreeMemory();

 
 /**
 
 /**

-    Open the @a url in user's default browser. If @a flags parameter contains
-    @c wxBROWSER_NEW_WINDOW flag, a new window is opened for the URL
-    (currently this is only supported under Windows). The @a url may also be a
-    local file path (with or without @c file:// prefix), if it doesn't
-    correspond to an existing file and the URL has no scheme @c http:// is
-    prepended to it by default.
-    Returns @true if the application was successfully launched.
-    Note that for some configurations of the running user, the application which
-    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).
+    Return the (current) user's home directory.
+
+    @see wxGetUserHome(), wxStandardPaths

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0);
+wxString wxGetHomeDir();

 
 /**
 
 /**

-    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".
+    Copies the current host machine's name into the supplied buffer. Please
+    note that the returned name is @e not fully qualified, i.e. it does not
+    include the domain name.
+
+    Under Windows or NT, this function first looks in the environment variable
+    SYSTEM_NAME; if this is not found, the entry @b HostName in the wxWidgets
+    section of the WIN.INI file is tried.
+
+    @returns The hostname if successful or an empty string otherwise.
+
+    @see wxGetFullHostName()

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-bool wxShell(const wxString& command = NULL);
+wxString wxGetHostName();

 
 /**
 
 /**

-    Gets the version and the operating system ID for currently running OS.
-    See wxPlatformInfo for more details about wxOperatingSystemId.
+    @deprecated Use wxGetHostName() instead.
+
+    @param buf Buffer to store the host name in.
+    @param sz  Size of the buffer.

 
 

-    @see ::wxGetOsDescription, wxPlatformInfo
+    @returns @true if successful, @false otherwise.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxOperatingSystemId wxGetOsVersion(int* major = NULL,
-                                    int* minor = NULL);
+bool wxGetHostName(char* buf, int sz);

 
 /**
     Returns the FQDN (fully qualified domain host name) or an empty string on
 
 /**
     Returns the FQDN (fully qualified domain host name) or an empty string on


@@ -475,170 +590,217 @@ wxOperatingSystemId wxGetOsVersion(int* major = NULL,
 wxString wxGetFullHostName();
 
 /**
 wxString wxGetFullHostName();
 
 /**

-    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.
+    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}
 */
 
     @header{wx/utils.h}
 */

-void wxPostDelete(wxObject* object);
+wxString wxGetUserHome(const wxString& user = "");

 
 /**
 
 /**

-    @b NB: This function is obsolete, please use
-    wxWindow::FindWindowByLabel instead.
-    Find a window by its label. Depending on the type of window, the label may be a
-    window title
-    or panel item label. If @a parent is @NULL, the search will start from all
-    top-level
-    frames and dialog boxes; if non-@NULL, the search will be limited to the given
-    window hierarchy.
-    The search is recursive in both cases.
+    This function returns the "user id" also known as "login name" under Unix
+    (i.e. something like "jsmith"). It uniquely identifies the current user (on
+    this system).  Under Windows or NT, this function first looks in the
+    environment variables USER and LOGNAME; if neither of these is found, the
+    entry @b UserId in the @b wxWidgets section of the WIN.INI file is tried.
+
+    @returns The login name if successful or an empty string otherwise.
+
+    @see wxGetUserName()

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxWindow* wxFindWindowByLabel(const wxString& label,
-                                wxWindow* parent = NULL);
+wxString wxGetUserId();

 
 

+/**
+    @deprecated Use wxGetUserId() instead.
+
+    @param buf Buffer to store the login name in.
+    @param sz  Size of the buffer.
+
+    @returns @true if successful, @false otherwise.
+
+    @header{wx/utils.h}
+*/
+bool wxGetUserId(char* buf, int sz);

 
 /**
 
 /**

-    Returns the mouse position in screen coordinates.
+    This function returns the full user name (something like "Mr. John Smith").
+
+    Under Windows or NT, this function looks for the entry UserName in the
+    wxWidgets section of the WIN.INI file. If PenWindows is running, the entry
+    Current in the section User of the PENWIN.INI file is used.
+
+    @returns The full user name if successful or an empty string otherwise.
+
+    @see wxGetUserId()

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxPoint wxGetMousePosition();
+wxString wxGetUserName();

 
 /**
 
 /**

-    Loads a user-defined Windows resource as a string. If the resource is found,
-    the function creates
-    a new character array and copies the data into it. A pointer to this data is
-    returned. If unsuccessful, @NULL is returned.
-    The resource must be defined in the @c .rc file using the following syntax:
+    @deprecated Use wxGetUserName() instead.

 
 

-    @code
-    myResource TEXT file.ext
-    @endcode
+    @param buf Buffer to store the full user name in.
+    @param sz  Size of the buffer.

 
 

-    where @c file.ext is a file that the resource compiler can find.
-    This function is available under Windows only.
+    @returns @true if successful, @false otherwise.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxString wxLoadUserResource(const wxString& resourceName,
-                            const wxString& resourceType = "TEXT");
+bool wxGetUserName(char* buf, int sz);

 
 /**
 
 /**

-    Returns the amount of free memory in bytes under environments which
-    support it, and -1 if not supported or failed to perform measurement.
+    Returns the string containing the description of the current platform in a
+    user-readable form. For example, this function may return strings like
+    "Windows NT Version 4.0" or "Linux 2.2.2 i386".
+
+    @see wxGetOsVersion()
+
+    @header{wx/utils.h}

 */
 */

-wxMemorySize wxGetFreeMemory();
+wxString wxGetOsDescription();

 
 

-//@{

 /**
 /**

-    Copies the current host machine's name into the supplied buffer. Please note
-    that the returned name is @e not fully qualified, i.e. it does not include
-    the domain name.
-    Under Windows or NT, this function first looks in the environment
-    variable SYSTEM_NAME; if this is not found, the entry @b HostName
-    in the @b wxWidgets section of the WIN.INI file is tried.
-    The first variant of this function returns the hostname if successful or an
-    empty string otherwise. The second (deprecated) function returns @true
-    if successful, @false otherwise.
+    Gets the version and the operating system ID for currently running OS. See
+    wxPlatformInfo for more details about wxOperatingSystemId.

 
 

-    @see wxGetFullHostName()
+    @see wxGetOsDescription(), wxPlatformInfo

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxString wxGetHostName();
-bool wxGetHostName(char* buf, int sz);
-//@}
+wxOperatingSystemId wxGetOsVersion(int* major = NULL, int* minor = NULL);

 
 /**
 
 /**

-    Under X only, returns the current display name. See also wxSetDisplayName().
+    Returns @true if the operating system the program is running under is 64
+    bit. The check is performed at run-time and may differ from the value
+    available at compile-time (at compile-time you can just check if
+    <tt>sizeof(void*) == 8</tt>) since the program could be running in
+    emulation mode or in a mixed 32/64 bit system (bi-architecture operating
+    system).
+
+    @note This function is not 100% reliable on some systems given the fact
+          that there isn't always a standard way to do a reliable check on the
+          OS architecture.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxString wxGetDisplayName();
+bool wxIsPlatform64Bit();

 
 /**
 
 /**

-    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.
+    Returns @true if the current platform is little endian (instead of big
+    endian). The check is performed at run-time.
+
+    @see @ref group_funcmacro_byteorder "Byte Order Functions and Macros"

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxString wxGetUserHome(const wxString& user = "");
+bool wxIsPlatformLittleEndian();
+
+//@}

 
 

+
+
+/** @ingroup group_funcmacro_procctrl */

 //@{
 //@{

+

 /**
 /**

-    @b wxPerl note: In wxPerl this function is called @c Wx::ExecuteStdoutStderr
-    and it only takes the @c command argument,
-    and returns a 3-element list @c ( status, output, errors ), where
-    @c output and @c errors are array references.

     Executes another program in Unix or Windows.
     Executes another program in Unix or Windows.

-    The first form takes a command string, such as @c "emacs file.txt".
-    The second form takes an array of values: a command, any number of
-    arguments, terminated by @NULL.
-    The semantics of the third and fourth versions is different from the first two
-    and is described in more details below.
-    If @a flags parameter contains @c wxEXEC_ASYNC flag (the default), flow
-    of control immediately returns. If it contains @c wxEXEC_SYNC, the current
-    application waits until the other program has terminated.
+
+    In the overloaded versions of this function, if @a flags parameter contains
+    @c wxEXEC_ASYNC flag (the default), flow of control immediately returns. If
+    it contains @c wxEXEC_SYNC, the current application waits until the other
+    program has terminated.
+

     In the case of synchronous execution, the return value is the exit code of
     In the case of synchronous execution, the return value is the exit code of

-    the process (which terminates by the moment the function returns) and will be
-    -1 if the process couldn't be started and typically 0 if the process
-    terminated successfully. Also, while waiting for the process to
-    terminate, wxExecute will call wxYield(). Because of this, by
-    default this function disables all application windows to avoid unexpected
-    reentrancies which could result from the users interaction with the program
-    while the child process is running. If you are sure that it is safe to not
-    disable the program windows, you may pass @c wxEXEC_NODISABLE flag to
-    prevent this automatic disabling from happening.
+    the process (which terminates by the moment the function returns) and will
+    be -1 if the process couldn't be started and typically 0 if the process
+    terminated successfully. Also, while waiting for the process to terminate,
+    wxExecute() will call wxYield(). Because of this, by default this function
+    disables all application windows to avoid unexpected reentrancies which
+    could result from the users interaction with the program while the child
+    process is running. If you are sure that it is safe to not disable the
+    program windows, you may pass @c wxEXEC_NODISABLE flag to prevent this
+    automatic disabling from happening.
+

     For asynchronous execution, however, the return value is the process id and
     zero value indicates that the command could not be executed. As an added
     complication, the return value of -1 in this case indicates that we didn't
     For asynchronous execution, however, the return value is the process id and
     zero value indicates that the command could not be executed. As an added
     complication, the return value of -1 in this case indicates that we didn't

-    launch a new process, but connected to the running one (this can only happen in
-    case of using DDE under Windows for command execution). In particular, in this,
-    and only this, case the calling code will not get the notification about
+    launch a new process, but connected to the running one (this can only
+    happen when using DDE under Windows for command execution). In particular,
+    in this case only, the calling code will not get the notification about

     process termination.
     process termination.

-    If callback isn't @NULL and if execution is asynchronous,
-    wxProcess::OnTerminate will be called when
-    the process finishes. Specifying this parameter also allows you to redirect the
-    standard input and/or output of the process being launched by calling
-    wxProcess::Redirect. If the child process IO is redirected,
-    under Windows the process window is not shown by default (this avoids having to
-    flush an unnecessary console for the processes which don't create any windows
+
+    If @a callback isn't @NULL and if execution is asynchronous,
+    wxProcess::OnTerminate() will be called when the process finishes.
+    Specifying this parameter also allows you to redirect the standard input
+    and/or output of the process being launched by calling
+    wxProcess::Redirect(). If the child process IO is redirected, under Windows
+    the process window is not shown by default (this avoids having to flush an
+    unnecessary console for the processes which don't create any windows

     anyhow) but a @c wxEXEC_NOHIDE flag can be used to prevent this from
     anyhow) but a @c wxEXEC_NOHIDE flag can be used to prevent this from

-    happening, i.e. with this flag the child process window will be shown normally.
-    Under Unix the flag @c wxEXEC_MAKE_GROUP_LEADER may be used to ensure
-    that the new process is a group leader (this will create a new session if
-    needed). Calling wxKill() passing wxKILL_CHILDREN will
-    kill this process as well as all of its children (except those which have
-    started their own session).
+    happening, i.e. with this flag the child process window will be shown
+    normally.
+
+    Under Unix the flag @c wxEXEC_MAKE_GROUP_LEADER may be used to ensure that
+    the new process is a group leader (this will create a new session if
+    needed). Calling wxKill() passing wxKILL_CHILDREN will kill this process as
+    well as all of its children (except those which have started their own
+    session).
+

     The @c wxEXEC_NOEVENTS flag prevents processing of any events from taking
     place while the child process is running. It should be only used for very
     short-lived processes as otherwise the application windows risk becoming
     The @c wxEXEC_NOEVENTS flag prevents processing of any events from taking
     place while the child process is running. It should be only used for very
     short-lived processes as otherwise the application windows risk becoming

-    unresponsive from the users point of view. As this flag only makes sense with
-    @c wxEXEC_SYNC, @c wxEXEC_BLOCK equal to the sum of both of these flags
-    is provided as a convenience.
-    Finally, you may use the third overloaded version of this function to execute
-    a process (always synchronously, the contents of @a flags is or'd with
-    @c wxEXEC_SYNC) and capture its output in the array @e output. The
-    fourth version adds the possibility to additionally capture the messages from
-    standard error output in the @a errors array.
-    @b NB: Currently wxExecute() can only be used from the main thread, calling
-    this function from another thread will result in an assert failure in debug
-    build and won't work.
+    unresponsive from the users point of view. As this flag only makes sense
+    with @c wxEXEC_SYNC, @c wxEXEC_BLOCK equal to the sum of both of these
+    flags is provided as a convenience.
+
+    @note Currently wxExecute() can only be used from the main thread, calling
+          this function from another thread will result in an assert failure in
+          debug build and won't work.

 
     @param command
 
     @param command

-        The command to execute and any parameters to pass to it as a
-        single string.
+        The command to execute and any parameters to pass to it as a single
+        string, i.e. "emacs file.txt".
+    @param flags
+        Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
+        wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
+        wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
+        their combination, in wxEXEC_SYNC case.
+    @param callback
+        An optional pointer to wxProcess.
+
+    @see wxShell(), wxProcess, @ref page_samples_exec
+
+    @header{wx/utils.h}
+
+    @beginWxPerlOnly
+    This function is called @c Wx::ExecuteStdoutStderr and it only takes the
+    @a command argument, and returns a 3-element list (@c status, @c output,
+    @c errors), where @c output and @c errors are array references.
+    @endWxPerlOnly
+*/
+long wxExecute(const wxString& command, int flags = wxEXEC_ASYNC,
+                wxProcess* callback = NULL);
+
+//@}
+
+/** @ingroup group_funcmacro_procctrl */
+//@{
+/**
+    This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
+    please see its documentation for general information.
+
+    This version takes an array of values: a command, any number of arguments,
+    terminated by @NULL.
+

     @param argv
     @param argv

-        The command to execute should be the first element of this
-        array, any additional ones are the command parameters and the array must be
+        The command to execute should be the first element of this array, any
+        additional ones are the command parameters and the array must be

         terminated with a @NULL pointer.
     @param flags
         Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
         terminated with a @NULL pointer.
     @param flags
         Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include


@@ -646,52 +808,61 @@ wxString wxGetUserHome(const wxString& user = "");
         wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
         their combination, in wxEXEC_SYNC case.
     @param callback
         wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
         their combination, in wxEXEC_SYNC case.
     @param callback

-        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);
-long wxExecute(char** argv,
-               int flags = wxEXEC_ASYNC,
-               wxProcess* callback = NULL);
-long wxExecute(wchar_t** argv,
-               int flags = wxEXEC_ASYNC,
-               wxProcess* callback = NULL);
-long wxExecute(const wxString& command,
-               wxArrayString& output,
-               int flags = 0);
-long wxExecute(const wxString& command,
-               wxArrayString& output,
-               wxArrayString& errors,
-               int flags = 0);
+        An optional pointer to wxProcess.
+
+    @header{wx/utils.h}
+*/
+long wxExecute(char** argv, int flags = wxEXEC_ASYNC,
+                wxProcess* callback = NULL);
+long wxExecute(wchar_t** argv, int flags = wxEXEC_ASYNC,
+                wxProcess* callback = NULL);

 //@}
 
 //@}
 

+/** @ingroup group_funcmacro_procctrl */
+//@{
+

 /**
 /**

-    Returns a string representing the current date and time.
+    This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
+    please see its documentation for general information.
+
+    This version can be used to execute a process (always synchronously, the
+    contents of @a flags is or'd with @c wxEXEC_SYNC) and capture its output in
+    the array @e output.
+
+    @param command
+        The command to execute and any parameters to pass to it as a single
+        string.
+    @param flags
+        Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
+        wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
+        wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
+        their combination, in wxEXEC_SYNC case.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxString wxNow();
+long wxExecute(const wxString& command, wxArrayString& output,
+                int flags = 0);

 
 /**
 
 /**

-    Returns @true if the operating system the program is running under is 64 bit.
-    The check is performed at run-time and may differ from the value available at
-    compile-time (at compile-time you can just check if @c sizeof(void*)==8)
-    since the program could be running in emulation mode or in a mixed 32/64 bit
-    system
-    (bi-architecture operating system).
-    Very important: this function is not 100% reliable on some systems given the
-    fact
-    that there isn't always a standard way to do a reliable check on the OS
-    architecture.
+    This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
+    please see its documentation for general information.
+
+    This version adds the possibility to additionally capture the messages from
+    standard error output in the @a errors array.
+
+    @param command
+        The command to execute and any parameters to pass to it as a single
+        string.
+    @param flags
+        Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
+        wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
+        wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
+        their combination, in wxEXEC_SYNC case.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-bool wxIsPlatform64Bit();
+long wxExecute(const wxString& command, wxArrayString& output,
+                wxArrayString& errors, int flags = 0);

 
 /**
     Returns the number uniquely identifying the current process in the system.
 
 /**
     Returns the number uniquely identifying the current process in the system.


@@ -703,12 +874,12 @@ unsigned long wxGetProcessId();
 
 /**
     Equivalent to the Unix kill function: send the given signal @a sig to the
 
 /**
     Equivalent to the Unix kill function: send the given signal @a sig to the

-    process with PID @e pid. The valid signal values are
+    process with PID @a pid. The valid signal values are:

 
     @code
     enum wxSignal
     {
 
     @code
     enum wxSignal
     {

-        wxSIGNONE = 0,  // verify if the process exists under Unix
+        wxSIGNONE = 0, // verify if the process exists under Unix

         wxSIGHUP,
         wxSIGINT,
         wxSIGQUIT,
         wxSIGHUP,
         wxSIGINT,
         wxSIGQUIT,


@@ -717,98 +888,125 @@ unsigned long wxGetProcessId();
         wxSIGABRT,
         wxSIGEMT,
         wxSIGFPE,
         wxSIGABRT,
         wxSIGEMT,
         wxSIGFPE,

-        wxSIGKILL,      // forcefully kill, dangerous!
+        wxSIGKILL,     // forcefully kill, dangerous!

         wxSIGBUS,
         wxSIGSEGV,
         wxSIGSYS,
         wxSIGPIPE,
         wxSIGALRM,
         wxSIGBUS,
         wxSIGSEGV,
         wxSIGSYS,
         wxSIGPIPE,
         wxSIGALRM,

-        wxSIGTERM       // terminate the process gently
+        wxSIGTERM      // terminate the process gently

     };
     @endcode
 
     };
     @endcode
 

-    @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning
-    under both Unix and Windows but all the other signals are equivalent to
+    @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning under
+    both Unix and Windows but all the other signals are equivalent to

     @c wxSIGTERM under Windows.
     @c wxSIGTERM under Windows.

-    Returns 0 on success, -1 on failure. If @a rc parameter is not @NULL, it will
-    be filled with an element of @c wxKillError enum:
+
+    Returns 0 on success, -1 on failure. If the @a rc parameter is not @NULL,
+    it will be filled with a value of the the @c wxKillError enum:

 
     @code
     enum wxKillError
     {
 
     @code
     enum wxKillError
     {

-        wxKILL_OK,              // no error
-        wxKILL_BAD_SIGNAL,      // no such signal
-        wxKILL_ACCESS_DENIED,   // permission denied
-        wxKILL_NO_PROCESS,      // no such process
-        wxKILL_ERROR            // another, unspecified error
+        wxKILL_OK,            // no error
+        wxKILL_BAD_SIGNAL,    // no such signal
+        wxKILL_ACCESS_DENIED, // permission denied
+        wxKILL_NO_PROCESS,    // no such process
+        wxKILL_ERROR          // another, unspecified error

     };
     @endcode
 
     };
     @endcode
 

-    The @a flags parameter can be wxKILL_NOCHILDREN (the default),
-    or wxKILL_CHILDREN, in which case the child processes of this
-    process will be killed too. Note that under Unix, for wxKILL_CHILDREN
-    to work you should have created the process by passing wxEXEC_MAKE_GROUP_LEADER
-    to wxExecute.
+    The @a flags parameter can be wxKILL_NOCHILDREN (the default), or
+    wxKILL_CHILDREN, in which case the child processes of this process will be
+    killed too. Note that under Unix, for wxKILL_CHILDREN to work you should
+    have created the process by passing wxEXEC_MAKE_GROUP_LEADER to
+    wxExecute().

 
 

-    @see wxProcess::Kill, wxProcess::Exists, @ref overview_sampleexec "Exec sample"
+    @see wxProcess::Kill(), wxProcess::Exists(), @ref page_samples_exec

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-int wxKill(long pid, int sig = wxSIGTERM, wxKillError rc = NULL,
-            int flags = 0);
+int wxKill(long pid, int sig = wxSIGTERM,
+            wxKillError rc = NULL, int flags = 0);

 
 /**
 
 /**

-    Returns the current state of the mouse.  Returns a wxMouseState
-    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.
+    Executes a command in an interactive shell window. If no command is
+    specified, then just the shell is spawned.
+
+    @see wxExecute(), @ref page_samples_exec

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxMouseState wxGetMouseState();
+bool wxShell(const wxString& command = NULL);

 
 

-//@{

 /**
 /**

-    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.
+    This function shuts down or reboots the computer depending on the value of
+    the @a flags.
+
+    @note Doing this requires the corresponding access rights (superuser under
+          Unix, SE_SHUTDOWN privilege under Windows NT) and that this function
+          is only implemented under Unix and Win32.
+
+    @param flags
+        Either wxSHUTDOWN_POWEROFF or wxSHUTDOWN_REBOOT
+
+    @returns @true on success, @false if an error occurred.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-wxString wxGetEmailAddress();
-bool wxGetEmailAddress(char* buf, int sz);
+bool wxShutdown(wxShutdownFlags flags);
+

 //@}
 
 //@}
 

+
+
+/** @ingroup group_funcmacro_time */
+//@{
+

 /**
 /**

-    Sleeps for the specified number of seconds.
+    Sleeps for the specified number of microseconds. The microsecond resolution
+    may 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 calling wxMilliSleep() with the argument of @e microseconds/1000.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-void wxSleep(int secs);
+void wxMicroSleep(unsigned long microseconds);

 
 /**
 
 /**

-    Returns @true if the current platform is little endian (instead of big
-    endian).
-    The check is performed at run-time.
+    Sleeps for the specified number of milliseconds. Notice that usage of this
+    function is encouraged instead of calling usleep(3) directly because the
+    standard @e usleep() function is not MT safe.

 
 

-    @see @ref overview_byteordermacros "Byte order macros"
+    @header{wx/utils.h}
+*/
+void wxMilliSleep(unsigned long milliseconds);
+
+/**
+    Returns a string representing the current date and time.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-bool wxIsPlatformLittleEndian();
+wxString wxNow();

 
 /**
 
 /**

-    Under X only, sets the current display name. This is the X host and display
-    name such
-    as "colonsay:0.0", and the function indicates which display should be used for
-    creating
-    windows from this point on. Setting the display within an application allows
-    multiple
-    displays to be used.
-    See also wxGetDisplayName().
+    Sleeps for the specified number of seconds.

 
     @header{wx/utils.h}
 */
 
     @header{wx/utils.h}
 */

-void wxSetDisplayName(const wxString& displayName);
+void wxSleep(int secs);
+
+/**
+    @deprecated This function is deprecated because its name is misleading:
+                notice that the argument is in milliseconds, not microseconds.
+                Please use either wxMilliSleep() or wxMicroSleep() depending on
+                the resolution you need.
+
+    Sleeps for the specified number of milliseconds.
+
+    @header{wx/utils.h}
+*/
+void wxUsleep(unsigned long milliseconds);
+
+//@}