Finished review/fixes of the rest of the functions and macro categories (Network...

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

diff --git a/docs/doxygen/groups/funcmacro_thread.h b/docs/doxygen/groups/funcmacro_thread.h
index 1bcd6a900206e8cb4692ca81bb9e0e32241e0dc6..4fdc5dd02af4956c3e14a459c10344c1ea4b5a4b 100644 (file)
--- a/docs/doxygen/groups/funcmacro_thread.h
+++ b/docs/doxygen/groups/funcmacro_thread.h
@@ -11,17 +11,15 @@
 @defgroup group_funcmacro_thread Threads
 @ingroup group_funcmacro
 
 @defgroup group_funcmacro_thread Threads
 @ingroup group_funcmacro
 

-The functions and macros here mainly exist to make it writing the code which
-may be compiled in multi thread build (wxUSE_THREADS = 1) as well as in single
-thread configuration (wxUSE_THREADS = 0).
+The functions and macros here mainly exist to make it possible to write code
+which may be compiled in multi thread build (wxUSE_THREADS = 1) as well as in
+single thread configuration (wxUSE_THREADS = 0).

 
 For example, a static variable must be protected against simultaneous access by
 multiple threads in the former configuration but in the latter the extra
 overhead of using the critical section is not needed. To solve this problem,
 
 For example, a static variable must be protected against simultaneous access by
 multiple threads in the former configuration but in the latter the extra
 overhead of using the critical section is not needed. To solve this problem,

-the wxCRITICAL_SECTION macro may be used to create and use the critical section
-only when needed.
-
-@header{wx/thread.h}
+the wxCRITICAL_SECTION() macro may be used to create and use the critical
+section only when needed.

 
 @sa wxThread, wxMutex, @ref overview_thread
 
 
 @sa wxThread, wxMutex, @ref overview_thread
 

diff --git a/interface/arrstr.h b/interface/arrstr.h
index ed3a25a44d5b8090b927930cbec8fefb609d6b17..34652fe1448082316bacb58c84108dd88bf343d7 100644 (file)
--- a/interface/arrstr.h
+++ b/interface/arrstr.h
@@ -350,6 +350,8 @@ public:
     separators.
 
     @see wxJoin()
     separators.
 
     @see wxJoin()

+
+    @header{wx/arrstr.h}

 */
 wxArrayString wxSplit(const wxString& str, const wxChar sep,
                       const wxChar escape = '\\');
 */
 wxArrayString wxSplit(const wxString& str, const wxChar sep,
                       const wxChar escape = '\\');


@@ -360,12 +362,15 @@ wxArrayString wxSplit(const wxString& str, const wxChar sep,
 
     If the @a escape character is non-@NULL, then it's used as prefix for each
     occurrence of @a sep in the strings contained in @a arr before joining them
 
     If the @a escape character is non-@NULL, then it's used as prefix for each
     occurrence of @a sep in the strings contained in @a arr before joining them

-    which is necessary in order to be able to recover the original array contents
-    from the string later using wxSplit().
+    which is necessary in order to be able to recover the original array
+    contents from the string later using wxSplit().

 
     @see wxSplit()
 
     @see wxSplit()

+
+    @header{wx/arrstr.h}

 */
 wxString wxJoin(const wxArrayString& arr, const wxChar sep,
                 const wxChar escape = '\\');
 
 //@}
 */
 wxString wxJoin(const wxArrayString& arr, const wxChar sep,
                 const wxChar escape = '\\');
 
 //@}

+

diff --git a/interface/chartype.h b/interface/chartype.h
index 4e8d4e4d57225cbbd3c1d0119b61c3a9d128a58c..af71092399929d06fe28edaa0b3130e9b32a4165 100644 (file)
--- a/interface/chartype.h
+++ b/interface/chartype.h
@@ -6,41 +6,54 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

+/** @ingroup group_funcmacro_string */

 //@{
 //@{

+

 /**
 /**

-    wxT() is a macro which can be used with character and string literals (in other
-    words, @c 'x' or @c "foo") to automatically convert them to Unicode in
-    Unicode build configuration. Please see the
-    @ref overview_unicode "Unicode overview" for more information.
-    This macro is simply returns the value passed to it without changes in ASCII
-    build. In fact, its definition is:
-
-    @code
-    #ifdef UNICODE
-    #define wxT(x) L ## x
-    #else // !Unicode
-    #define wxT(x) x
-    #endif
-    @endcode
-*/
-wxChar wxT(char ch);
-const wxChar* wxT(const char* s);
-//@}
+    This macro can be used with character and string literals (in other words,
+    @c 'x' or @c "foo") to automatically convert them to Unicode in Unicode
+    builds of wxWidgets. This macro is simply returns the value passed to it
+    without changes in ASCII build. In fact, its definition is:

 
 

+@code
+#ifdef UNICODE
+#   define wxT(x) L ## x
+#else // !Unicode
+#   define wxT(x) x
+#endif
+@endcode
+
+    @see @ref overview_unicode
+
+    @header{wx/chartype.h}
+*/
+#define wxT(string)

 
 

-//@{

 /**
     wxS is macro which can be used with character and string literals to either
     convert them to wide characters or strings in @c wchar_t-based Unicode
     builds or keep them unchanged in UTF-8 builds. The use of this macro is
 /**
     wxS is macro which can be used with character and string literals to either
     convert them to wide characters or strings in @c wchar_t-based Unicode
     builds or keep them unchanged in UTF-8 builds. The use of this macro is

-    optional as the translation will always be done at run-time even if there is a
-    mismatch between the kind of the literal used and wxStringCharType used in the
-    current build, but using it can be beneficial in performance-sensitive code to
-    do the conversion at compile-time instead.
+    optional as the translation will always be done at run-time even if there
+    is a mismatch between the kind of the literal used and string or character
+    type used in the current build, but using it can be beneficial in
+    performance-sensitive code to do the conversion at compile-time instead.

 
     @see wxT()
 
     @see wxT()

+
+    @header{wx/chartype.h}

 */
 */

-wxStringCharType wxS(char ch);
-const wxStringCharType* wxS(const char* s);
-//@}
+#define wxS(string)
+
+/**
+    This macro is exactly the same as wxT() and is defined in wxWidgets simply
+    because it may be more intuitive for Windows programmers as the standard
+    Win32 headers also define it (as well as yet another name for the same
+    macro which is _TEXT()).
+
+    Don't confuse this macro with _()!

 
 

+    @header{wx/chartype.h}
+*/
+#define _T(string)
+
+//@}

diff --git a/interface/intl.h b/interface/intl.h
index 7848d527b039925c8580cd4147ec066061985d9d..aef176653bec92c47151be8a0ff4142635f518d0 100644 (file)
--- a/interface/intl.h
+++ b/interface/intl.h
@@ -537,29 +537,34 @@ public:
 // Global functions/macros
 // ============================================================================
 
 // Global functions/macros
 // ============================================================================
 

+/** @ingroup group_funcmacro_string */
+//@{
+

 /**
 /**

-    This macro is identical to _() but for the plural variant
-    of wxGetTranslation().
+    This macro is identical to _() but for the plural variant of
+    wxGetTranslation().
+
+    @returns A const wxString.
+
+    @header{wx/intl.h}

 */
 */

-#define const wxString wxPLURAL(const wxString& sing,
-const wxString& plur,
-size_t n)     /* implementation is private */
+#define wxPLURAL(string, plural, n)

 
 /**
 
 /**

-    This macro doesn't do anything in the program code -- it simply expands to the
-    value of its argument.
+    This macro doesn't do anything in the program code -- it simply expands to
+    the value of its argument.
+

     However it does have a purpose which is to mark the literal strings for the
     extraction into the message catalog created by @c xgettext program. Usually
     However it does have a purpose which is to mark the literal strings for the
     extraction into the message catalog created by @c xgettext program. Usually

-    this is achieved using _() but that macro not only marks
-    the string for extraction but also expands into a
-    wxGetTranslation() function call which means that it
-    cannot be used in some situations, notably for static array
+    this is achieved using _() but that macro not only marks the string for
+    extraction but also expands into a wxGetTranslation() call which means that
+    it cannot be used in some situations, notably for static array

     initialization.
     initialization.

+

     Here is an example which should make it more clear: suppose that you have a
     static array of strings containing the weekday names and which have to be
     Here is an example which should make it more clear: suppose that you have a
     static array of strings containing the weekday names and which have to be

-    translated (note that it is a bad example, really, as
-    wxDateTime already can be used to get the localized week
-    day names already). If you write
+    translated (note that it is a bad example, really, as wxDateTime already
+    can be used to get the localized week day names already). If you write:

 
     @code
     static const char * const weekdays[] = { _("Mon"), ..., _("Sun") };
 
     @code
     static const char * const weekdays[] = { _("Mon"), ..., _("Sun") };


@@ -567,8 +572,8 @@ size_t n)     /* implementation is private */
     // use weekdays[n] as usual
     @endcode
 
     // use weekdays[n] as usual
     @endcode
 

-    the code wouldn't compile because the function calls are forbidden in the array
-    initializer. So instead you should do
+    The code wouldn't compile because the function calls are forbidden in the
+    array initializer. So instead you should do this:

 
     @code
     static const char * const weekdays[] = { wxTRANSLATE("Mon"), ...,
 
     @code
     static const char * const weekdays[] = { wxTRANSLATE("Mon"), ...,


@@ -577,60 +582,80 @@ size_t n)     /* implementation is private */
     // use wxGetTranslation(weekdays[n])
     @endcode
 
     // use wxGetTranslation(weekdays[n])
     @endcode
 

-    here.

     Note that although the code @b would compile if you simply omit
     Note that although the code @b would compile if you simply omit

-    wxTRANSLATE() in the above, it wouldn't work as expected because there would be
-    no translations for the weekday names in the program message catalog and
-    wxGetTranslation wouldn't find them.
+    wxTRANSLATE() in the above, it wouldn't work as expected because there
+    would be no translations for the weekday names in the program message
+    catalog and wxGetTranslation() wouldn't find them.
+
+    @returns A const wxChar*.
+
+    @header{wx/intl.h}

 */
 */

-#define const wxChar* wxTRANSLATE(const char* s)     /* implementation is private */
+#define wxTRANSLATE(string)

 
 /**
 
 /**

-    This macro expands into a call to wxGetTranslation()
-    function, so it marks the message for the extraction by @c xgettext just as
-    wxTRANSLATE() does, but also returns the translation of
-    the string for the current locale during execution.
-    Don't confuse this macro with _T()!
+    This function returns the translation of @a string in the current
+    @c locale(). If the string is not found in any of the loaded message
+    catalogs (see @ref overview_i18n), the original string is returned. In
+    debug build, an error message is logged -- this should help to find the
+    strings which were not yet translated.  If @a domain is specified then only
+    that domain/catalog is searched for a matching string.  As this function is
+    used very often, an alternative (and also common in Unix world) syntax is
+    provided: the _() macro is defined to do the same thing as
+    wxGetTranslation().
+
+    This function calls wxLocale::GetString().
+
+    @note This function is not suitable for literal strings in Unicode builds
+          since the literal strings must be enclosed into _T() or wxT() macro
+          which makes them unrecognised by @c xgettext, and so they are not
+          extracted to the message catalog. Instead, use the _() and wxPLURAL()
+          macro for all literal strings.
+
+    @see wxGetTranslation(const wxString&, const wxString&, size_t, const wxString&)
+
+    @header{wx/intl.h}

 */
 */

-const wxString _(const wxString& s);
+const wxString wxGetTranslation(const wxString& string,
+                                 const wxString& domain = wxEmptyString);

 
 

-//@{

 /**
 /**

-    This function returns the translation of string @a str in the current
-    locale(). If the string is not found in any of the loaded
-    message catalogs (see @ref overview_internationalization "internationalization
-    overview"), the
-    original string is returned. In debug build, an error message is logged -- this
-    should help to find the strings which were not yet translated.  If
-    @a domain is specified then only that domain/catalog is searched
-    for a matching string.  As this function
-    is used very often, an alternative (and also common in Unix world) syntax is
-    provided: the _() macro is defined to do the same thing
-    as wxGetTranslation.
-    The second form is used when retrieving translation of string that has
-    different singular and plural form in English or different plural forms in some
-    other language. It takes two extra arguments: as above, @e str
-    parameter must contain the singular form of the string to be converted and
-    is used as the key for the search in the catalog. The @a strPlural parameter
-    is the plural form (in English). The parameter @a n is used to determine the
-    plural form.  If no message catalog is found @a str is returned if 'n == 1',
-    otherwise @e strPlural.
-    See GNU gettext manual
-    for additional information on plural forms handling. For a shorter alternative
-    see the wxPLURAL() macro.
-    Both versions call wxLocale::GetString.
-    Note that this function is not suitable for literal strings in Unicode
-    builds, since the literal strings must be enclosed into
-    _T() or wxT() macro which makes them
-    unrecognised by @c xgettext, and so they are not extracted to the message
-    catalog. Instead, use the _() and
-    wxPLURAL() macro for all literal strings.
+    This is an overloaded version of
+    wxGetTranslation(const wxString&, const wxString&), please see its
+    documentation for general information.
+
+    This version is used when retrieving translation of string that has
+    different singular and plural forms in English or different plural forms in
+    some other language. Like wxGetTranslation(const wxString&,const wxString&),
+    the @a string parameter must contain the singular form of the string to be
+    converted and is used as the key for the search in the catalog. The
+    @a plural parameter is the plural form (in English). The parameter @a n is
+    used to determine the plural form. If no message catalog is found,
+    @a string is returned if "n == 1", otherwise @a plural is returned.
+
+    See GNU gettext Manual for additional information on plural forms handling:
+    <http://www.gnu.org/software/gettext/manual/gettext.html#Plural-forms>
+    For a shorter alternative see the wxPLURAL() macro.
+
+    This function calls wxLocale::GetString().
+
+    @header{wx/intl.h}

 */
 */

-const wxString wxGetTranslation(const wxString& str,
-                                const wxString& domain = wxEmptyString);
-const wxString wxGetTranslation(const wxString& str,
-                                const wxString& strPlural,
-                                size_t n,
-                                const wxString& domain = wxEmptyString);
+const wxString wxGetTranslation(const wxString& string,
+                                 const wxString& plural, size_t n,
+                                 const wxString& domain = wxEmptyString);
+
+/**
+    This macro expands into a call to wxGetTranslation(), so it marks the
+    message for the extraction by @c xgettext just as wxTRANSLATE() does, but
+    also returns the translation of the string for the current locale during
+    execution.
+
+    Don't confuse this with _T()!
+
+    @header{wx/intl.h}
+*/
+const wxString _(const wxString& string);
+

 //@}
 
 //@}
 

diff --git a/interface/stopwatch.h b/interface/stopwatch.h
index 982cb0571ca08ffa2acf520749c19c0485c07945..3dfba4a146301708c94bae18f837840140c9f03c 100644 (file)
--- a/interface/stopwatch.h
+++ b/interface/stopwatch.h
@@ -72,24 +72,35 @@ public:
 // Global functions/macros
 // ============================================================================
 
 // Global functions/macros
 // ============================================================================
 

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

 /**
     Returns the number of seconds since local time 00:00:00 Jan 1st 1970.
 
 /**
     Returns the number of seconds since local time 00:00:00 Jan 1st 1970.
 

-    @see wxDateTime::Now
+    @see wxDateTime::Now()
+
+    @header{wx/stopwatch.h}

 */
 long wxGetLocalTime();
 
 /**
 */
 long wxGetLocalTime();
 
 /**

-    Returns the number of seconds since GMT 00:00:00 Jan 1st 1970.
+    Returns the number of milliseconds since local time 00:00:00 Jan 1st 1970.

 
 

-    @see wxDateTime::Now
+    @see wxDateTime::Now(), wxLongLong
+
+    @header{wx/stopwatch.h}

 */
 */

-long wxGetUTCTime();
+wxLongLong wxGetLocalTimeMillis();

 
 /**
 
 /**

-    Returns the number of milliseconds since local time 00:00:00 Jan 1st 1970.
+    Returns the number of seconds since GMT 00:00:00 Jan 1st 1970.
+
+    @see wxDateTime::Now()

 
 

-    @see wxDateTime::Now, wxLongLong
+    @header{wx/stopwatch.h}

 */
 */

-wxLongLong wxGetLocalTimeMillis();
+long wxGetUTCTime();
+
+//@}

 
 

diff --git a/interface/thread.h b/interface/thread.h
index 4d086f25700340d06f40f424c821c0f15b578b21..c7eca68d19c64fee0d5dc91fa0245d4d83cb1694 100644 (file)
--- a/interface/thread.h
+++ b/interface/thread.h
@@ -926,17 +926,41 @@ public:
 // Global functions/macros
 // ============================================================================
 
 // Global functions/macros
 // ============================================================================
 

+/** @ingroup group_funcmacro_thread */
+//@{
+

 /**
 /**

-    Returns @true if this thread is the main one. Always returns @true if
-    @c wxUSE_THREADS is 0.
+    This macro declares a (static) critical section object named @a cs if
+    @c wxUSE_THREADS is 1 and does nothing if it is 0.
+
+    @header{wx/thread.h}

 */
 */

-bool wxIsMainThread();
+#define wxCRIT_SECT_DECLARE(cs)
+
+/**
+    This macro declares a critical section object named @a cs if
+    @c wxUSE_THREADS is 1 and does nothing if it is 0. As it doesn't include
+    the @c static keyword (unlike wxCRIT_SECT_DECLARE()), it can be used to
+    declare a class or struct member which explains its name.
+
+    @header{wx/thread.h}
+*/
+#define wxCRIT_SECT_DECLARE_MEMBER(cs)

 
 /**
 
 /**

-    This macro combines wxCRIT_SECT_DECLARE() and
-    wxCRIT_SECT_LOCKER(): it creates a static critical
-    section object and also the lock object associated with it. Because of this, it
-    can be only used inside a function, not at global scope. For example:
+    This macro creates a wxCriticalSectionLocker named @a name and associated
+    with the critical section @a cs if @c wxUSE_THREADS is 1 and does nothing
+    if it is 0.
+
+    @header{wx/thread.h}
+*/
+#define wxCRIT_SECT_LOCKER(name, cs)
+
+/**
+    This macro combines wxCRIT_SECT_DECLARE() and wxCRIT_SECT_LOCKER(): it
+    creates a static critical section object and also the lock object
+    associated with it. Because of this, it can be only used inside a function,
+    not at global scope. For example:

 
     @code
     int IncCount()
 
     @code
     int IncCount()


@@ -949,35 +973,56 @@ bool wxIsMainThread();
     }
     @endcode
 
     }
     @endcode
 

-    (note that we suppose that the function is called the first time from the main
-    thread so that the critical section object is initialized correctly by the time
-    other threads start calling it, if this is not the case this approach can
-    @b not be used and the critical section must be made a global instead).
+    Note that this example assumes that the function is called the first time
+    from the main thread so that the critical section object is initialized
+    correctly by the time other threads start calling it, if this is not the
+    case this approach can @b not be used and the critical section must be made
+    a global instead.
+
+    @header{wx/thread.h}

 */
 */

-#define wxCRITICAL_SECTION(name)     /* implementation is private */
+#define wxCRITICAL_SECTION(name)

 
 /**
 
 /**

-    This macro declares a critical section object named @a cs if
-    @c wxUSE_THREADS is 1 and does nothing if it is 0. As it doesn't
-    include the @c static keyword (unlike
-    wxCRIT_SECT_DECLARE()), it can be used to declare
-    a class or struct member which explains its name.
+    This macro is equivalent to
+    @ref wxCriticalSection::Leave "critical_section.Leave()" if
+    @c wxUSE_THREADS is 1 and does nothing if it is 0.
+
+    @header{wx/thread.h}
+*/
+#define wxLEAVE_CRIT_SECT(critical_section)
+
+/**
+    This macro is equivalent to
+    @ref wxCriticalSection::Enter "critical_section.Enter()" if
+    @c wxUSE_THREADS is 1 and does nothing if it is 0.
+
+    @header{wx/thread.h}
+*/
+#define wxENTER_CRIT_SECT(critical_section)
+
+/**
+    Returns @true if this thread is the main one. Always returns @true if
+    @c wxUSE_THREADS is 0.
+
+    @header{wx/thread.h}

 */
 */

-#define wxCRIT_SECT_DECLARE(cs)     /* implementation is private */
+bool wxIsMainThread();

 
 /**
     This function must be called when any thread other than the main GUI thread
 
 /**
     This function must be called when any thread other than the main GUI thread

-    wants to get access to the GUI library. This function will block the execution
-    of the calling thread until the main thread (or any other thread holding the
-    main GUI lock) leaves the GUI library and no other thread will enter the GUI
-    library until the calling thread calls ::wxMutexGuiLeave.
+    wants to get access to the GUI library. This function will block the
+    execution of the calling thread until the main thread (or any other thread
+    holding the main GUI lock) leaves the GUI library and no other thread will
+    enter the GUI library until the calling thread calls wxMutexGuiLeave().
+

     Typically, these functions are used like this:
 
     @code
     void MyThread::Foo(void)
     {
     Typically, these functions are used like this:
 
     @code
     void MyThread::Foo(void)
     {

-        // before doing any GUI calls we must ensure that this thread is the only
-        // one doing it!
+        // before doing any GUI calls we must ensure that
+        // this thread is the only one doing it!

 
         wxMutexGuiEnter();
 
 
         wxMutexGuiEnter();
 


@@ -988,36 +1033,25 @@ bool wxIsMainThread();
     }
     @endcode
 
     }
     @endcode
 

-    Note that under GTK, no creation of top-level windows is allowed in any
-    thread but the main one.

     This function is only defined on platforms which support preemptive
     threads.
     This function is only defined on platforms which support preemptive
     threads.

+
+    @note Under GTK, no creation of top-level windows is allowed in any thread
+          but the main one.
+
+    @header{wx/thread.h}

 */
 void wxMutexGuiEnter();
 
 /**
 */
 void wxMutexGuiEnter();
 
 /**

-    This macro declares a (static) critical section object named @a cs if
-    @c wxUSE_THREADS is 1 and does nothing if it is 0.
-*/
-#define wxCRIT_SECT_DECLARE(cs)     /* implementation is private */
+    This function is only defined on platforms which support preemptive
+    threads.

 
 

-/**
-    This macro is equivalent to @ref wxCriticalSection::leave cs.Leave if
-    @c wxUSE_THREADS is 1 and does nothing if it is 0.
-*/
-#define wxLEAVE_CRIT_SECT(wxCriticalSection& cs)     /* implementation is private */
+    @see wxMutexGuiEnter()

 
 

-/**
-    This macro creates a @ref overview_wxcriticalsectionlocker "critical section
-    lock"
-    object named @a name and associated with the critical section @a cs if
-    @c wxUSE_THREADS is 1 and does nothing if it is 0.
+    @header{wx/thread.h}

 */
 */

-#define wxCRIT_SECT_LOCKER(name, cs)     /* implementation is private */
+void wxMutexGuiLeave();

 
 

-/**
-    This macro is equivalent to @ref wxCriticalSection::enter cs.Enter if
-    @c wxUSE_THREADS is 1 and does nothing if it is 0.
-*/
-#define wxENTER_CRIT_SECT(wxCriticalSection& cs)     /* implementation is private */
+//@}

 
 

diff --git a/interface/utils.h b/interface/utils.h
index 01cbd0b2c4ccad48fe5c52aafea93a867b427e74..ec44158cadcf64a3a544ecb3c24425237a6a60a5 100644 (file)
--- a/interface/utils.h
+++ b/interface/utils.h
@@ -426,208 +426,299 @@ wxString wxStripMenuCodes(const wxString& str, int flags = wxStrip_All);
 
 
 
 
 
 

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

 
 

+/**
+    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();

 
 /**
 
 /**

-    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.
+    @deprecated Use wxGetEmailAddress() instead.

 
 

-    @return Returns the login name if successful or an empty string otherwise.
+    @param buf Buffer to store the email address in.
+    @param sz  Size of the buffer.

 
 

-    @see wxGetUserName()
+    @returns @true if successful, @false otherwise.

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

-wxString wxGetUserId();
+bool wxGetEmailAddress(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.
+
+    @header{wx/utils.h}
+*/
+wxMemorySize wxGetFreeMemory();
+
+/**
+    Return the (current) user's home directory.
+
+    @see wxGetUserHome(), wxStandardPaths
+
+    @header{wx/utils.h}
+*/
+wxString wxGetHomeDir();
+
+/**
+    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}
+*/
+wxString wxGetHostName();

 
 /**
 
 /**

-    @deprecated
-    This form is deprecated, use wxGetUserId() version that returns wxString.
+    @deprecated Use wxGetHostName() instead.

 
 

-    @param buf Buffer to store login name in.
+    @param buf Buffer to store the host name in.

     @param sz  Size of the buffer.
 
     @param sz  Size of the buffer.
 

-    @return Returns @true if successful, @false otherwise.
- */
-bool wxGetUserId(char* buf, int sz);
+    @returns @true if successful, @false otherwise.
+
+    @header{wx/utils.h}
+*/
+bool wxGetHostName(char* buf, int sz);

 
 /**
 
 /**

-    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.
+    Returns the FQDN (fully qualified domain host name) or an empty string on
+    error.

 
 

-    @see ::wxGetOsVersion
+    @see wxGetHostName()

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

-wxString wxGetOsDescription();
+wxString wxGetFullHostName();

 
 /**
 
 /**

-    Return the (current) user's home directory.
+    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).

 
 

-    @see wxGetUserHome(), wxStandardPaths
+    If the home directory couldn't be determined, an empty string is returned.

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

-wxString wxGetHomeDir();
+wxString wxGetUserHome(const wxString& user = "");

 
 /**
 
 /**

-    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.
+    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}
 */

-void wxMilliSleep(unsigned long milliseconds);
+wxString wxGetUserId();

 
 /**
 
 /**

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

-void wxMicroSleep(unsigned long microseconds);
+bool wxGetUserId(char* buf, int sz);

 
 /**
 
 /**

-    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".
+    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}
 */

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

 
 /**
 
 /**

-    Gets the version and the operating system ID for currently running OS.
-    See wxPlatformInfo for more details about wxOperatingSystemId.
+    @deprecated Use wxGetUserName() instead.
+
+    @param buf Buffer to store the full user 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 wxGetUserName(char* buf, int sz);

 
 /**
 
 /**

-    Returns the FQDN (fully qualified domain host name) or an empty string on
-    error.
+    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 wxGetHostName()
+    @see wxGetOsVersion()

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

-wxString wxGetFullHostName();
+wxString wxGetOsDescription();

 
 /**
 
 /**

-    Returns the amount of free memory in bytes under environments which
-    support it, and -1 if not supported or failed to perform measurement.
+    Gets the version and the operating system ID for currently running OS. See
+    wxPlatformInfo for more details about wxOperatingSystemId.
+
+    @see wxGetOsDescription(), wxPlatformInfo
+
+    @header{wx/utils.h}

 */
 */

-wxMemorySize wxGetFreeMemory();
+wxOperatingSystemId wxGetOsVersion(int* major = NULL, int* minor = NULL);

 
 

-//@{

 /**
 /**

-    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.
+    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).

 
 

-    @see wxGetFullHostName()
+    @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 wxGetHostName();
-bool wxGetHostName(char* buf, int sz);
-//@}
+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


@@ -635,52 +726,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.


@@ -692,12 +792,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,


@@ -706,59 +806,107 @@ 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);

 
 

-//@{

 /**
 /**

-    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.
+    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}
 */

-wxString wxGetEmailAddress();
-bool wxGetEmailAddress(char* buf, int sz);
+bool wxShell(const wxString& command = NULL);
+
+/**
+    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}
+*/
+bool wxShutdown(wxShutdownFlags flags);
+

 //@}
 
 //@}
 

+
+
+/** @ingroup group_funcmacro_time */
+//@{
+
+/**
+    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}
+*/
+void wxMicroSleep(unsigned long microseconds);
+
+/**
+    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.
+
+    @header{wx/utils.h}
+*/
+void wxMilliSleep(unsigned long milliseconds);
+
+/**
+    Returns a string representing the current date and time.
+
+    @header{wx/utils.h}
+*/
+wxString wxNow();
+

 /**
     Sleeps for the specified number of seconds.
 
 /**
     Sleeps for the specified number of seconds.
 


@@ -767,13 +915,16 @@ bool wxGetEmailAddress(char* buf, int sz);
 void wxSleep(int secs);
 
 /**
 void wxSleep(int secs);
 
 /**

-    Returns @true if the current platform is little endian (instead of big
-    endian).
-    The check is performed at run-time.
+    @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.

 
 

-    @see @ref overview_byteordermacros "Byte order macros"
+    Sleeps for the specified number of milliseconds.

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

-bool wxIsPlatformLittleEndian();
+void wxUsleep(unsigned long milliseconds);
+
+//@}

 
 

diff --git a/interface/wxcrt.h b/interface/wxcrt.h
index f51ad2243b3bc7a80b57199a20d653d8360739ed..d51d80bd5eb7399b1129d46c96d0fd107184b713 100644 (file)
--- a/interface/wxcrt.h
+++ b/interface/wxcrt.h
@@ -6,94 +6,118 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

+/** @ingroup group_funcmacro_string */
+//@{
+

 /**
 /**

-Returns a negative value, 0, or positive value if @a p1 is less than, equal
-to or greater than @e p2. The comparison is case-sensitive.
-This function complements the standard C function @e stricmp() which performs
-case-insensitive comparison.
-*/
-int wxStrcmp(const char* p1, const char* p2);
+    @returns @true if the pointer is either @NULL or points to an empty string,
+             @false otherwise.

 
 

+    @header{wx/wxcrt.h}
+*/
+bool wxIsEmpty(const char* p);

 
 /**
 
 /**

-@b NB: This function is obsolete, use wxString instead.
-A macro defined as:
+    This is a safe version of standard function @e strlen(): it does exactly
+    the same thing (i.e. returns the length of the string) except that it
+    returns 0 if @a p is the @NULL pointer.

 
 

-@code
-#define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0))
-@endcode
+    @header{wx/wxcrt.h}

 */
 */

-bool wxStringEq(const wxString& s1, const wxString& s2);
+size_t wxStrlen(const char* p);

 
 /**
 
 /**

-    @b NB: This function is obsolete, use wxString::Find instead.
-    Returns @true if the substring @a s1 is found within @e s2,
-    ignoring case if @a exact is @false. If @a subString is @false,
-    no substring matching is done.
+    This function complements the standard C function @e stricmp() which
+    performs case-insensitive comparison.
+
+    @returns A negative value, 0, or positive value if @a p1 is less than,
+             equal to or greater than @a p2. The comparison is case-sensitive.
+
+    @header{wx/wxcrt.h}

 */
 */

-bool wxStringMatch(const wxString& s1, const wxString& s2,
-                   bool subString = true,
-                   bool exact = false);
+int wxStrcmp(const char* p1, const char* p2);

 
 /**
 
 /**

-    This function replaces the dangerous standard function @c sprintf() and is
-    like @c snprintf() available on some platforms. The only difference with
-    sprintf() is that an additional argument - buffer size - is taken and the
-    buffer is never overflowed.
-    Returns the number of characters copied to the buffer or -1 if there is not
-    enough space.
+    This function complements the standard C function @e strcmp() which performs
+    case-sensitive comparison.
+
+    @returns A negative value, 0, or positive value if @a p1 is less than,
+             equal to or greater than @e p2. The comparison is case-insensitive.

 
 

-    @see wxVsnprintf(), wxString::Printf
+    @header{wx/wxcrt.h}

 */
 */

-int wxSnprintf(wxChar* buf, size_t len, const wxChar* format,
-               ...);
+int wxStricmp(const char* p1, const char* p2);

 
 /**
 
 /**

-    This is a convenience function wrapping
-    wxStringTokenizer which simply returns all tokens
-    found in the given @a str in an array.
-    Please see
-    wxStringTokenizer::wxStringTokenizer
-    for the description of the other parameters.
+    @deprecated Use wxString instead.
+
+    This macro is defined as:
+
+    @code
+    #define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0))
+    @endcode
+
+    @header{wx/wxcrt.h}

 */
 */

-wxArrayString wxStringTokenize(const wxString& str,
-                               const wxString& delims = wxDEFAULT_DELIMITERS,
-                               wxStringTokenizerMode mode = wxTOKEN_DEFAULT);
+bool wxStringEq(const wxString& s1, const wxString& s2);

 
 /**
 
 /**

-    This is a safe version of standard function @e strlen(): it does exactly the
-    same thing (i.e. returns the length of the string) except that it returns 0 if
-    @a p is the @NULL pointer.
+    @deprecated Use wxString::Find() instead.
+
+    Returns @true if the substring @a s1 is found within @a s2, ignoring case
+    if @a exact is @false. If @a subString is @false, no substring matching is
+    done.
+
+    @header{wx/wxcrt.h}

 */
 */

-size_t wxStrlen(const char* p);
+bool wxStringMatch(const wxString& s1, const wxString& s2,
+                   bool subString = true, bool exact = false);

 
 /**
 
 /**

-    The same as wxSnprintf() but takes a @c va_list
-    argument instead of arbitrary number of parameters.
-    Note that if @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports
-    positional arguments (see wxString::Printf for more information).
-    However other functions of the same family (wxPrintf, wxSprintf, wxFprintf,
-    wxVfprintf,
-    wxVfprintf, wxVprintf, wxVsprintf) currently do not to support positional
-    parameters
-    even when @c wxUSE_PRINTF_POS_PARAMS is 1.
-
-    @see wxSnprintf(), wxString::PrintfV
+    This is a convenience function wrapping wxStringTokenizer which simply
+    returns all tokens found in the given @a string in an array.
+
+    Please see wxStringTokenizer::wxStringTokenizer() for a description of the
+    other parameters.
+
+    @header{wx/wxcrt.h}

 */
 */

-int wxVsnprintf(wxChar* buf, size_t len, const wxChar* format,
-                va_list argPtr);
+wxArrayString wxStringTokenize(const wxString& string,
+                               const wxString& delims = wxDEFAULT_DELIMITERS,
+                               wxStringTokenizerMode mode = wxTOKEN_DEFAULT);

 
 /**
 
 /**

-    Returns @true if the pointer is either @NULL or points to an empty
-    string, @false otherwise.
+    This function replaces the dangerous standard function @e sprintf() and is
+    like @e snprintf() available on some platforms. The only difference with
+    @e sprintf() is that an additional argument - buffer size - is taken and
+    the buffer is never overflowed.
+
+    Returns the number of characters copied to the buffer or -1 if there is not
+    enough space.
+
+    @see wxVsnprintf(), wxString::Printf()
+
+    @header{wx/wxcrt.h}

 */
 */

-bool wxIsEmpty(const char* p);
+int wxSnprintf(wxChar* buf, size_t len, const wxChar* format, ...);

 
 /**
 
 /**

-    Returns a negative value, 0, or positive value if @a p1 is less than, equal
-    to or greater than @e p2. The comparison is case-insensitive.
-    This function complements the standard C function @e strcmp() which performs
-    case-sensitive comparison.
+    The same as wxSnprintf() but takes a @c va_list argument instead of an
+    arbitrary number of parameters.
+
+    @note If @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function
+          supports positional arguments (see wxString::Printf() for more
+          information). However other functions of the same family (wxPrintf(),
+          wxSprintf(), wxFprintf(), wxVfprintf(), wxVfprintf(), wxVprintf(),
+          wxVsprintf()) currently do not to support positional parameters even
+          when @c wxUSE_PRINTF_POS_PARAMS is 1.
+
+    @see wxSnprintf(), wxString::PrintfV()
+
+    @header{wx/wxcrt.h}

 */
 */

-int wxStricmp(const char* p1, const char* p2);
+int wxVsnprintf(wxChar* buf, size_t len,
+                const wxChar* format, va_list argPtr);
+
+//@}