Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Finished review/fixes of the rest of the functions and macro categories (Network/User/OS, Process Control, Strings, Threads, and Time).

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52790 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Bryan Petty
2008-03-25 07:36:12 +00:00
parent 9a8909371b
commit 3950d49c4f
8 changed files with 700 additions and 439 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/doxygen/groups/funcmacro_thread.h
View File

@@ -11,17 +11,15 @@
@defgroup group_funcmacro_thread Threads @defgroup group_funcmacro_thread Threads
@ingroup group_funcmacro @ingroup group_funcmacro
The functions and macros here mainly exist to make it writing the code which The functions and macros here mainly exist to make it possible to write code
may be compiled in multi thread build (wxUSE_THREADS = 1) as well as in single which may be compiled in multi thread build (wxUSE_THREADS = 1) as well as in
thread configuration (wxUSE_THREADS = 0). single thread configuration (wxUSE_THREADS = 0).
For example, a static variable must be protected against simultaneous access by For example, a static variable must be protected against simultaneous access by
multiple threads in the former configuration but in the latter the extra 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, 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 the wxCRITICAL_SECTION() macro may be used to create and use the critical
only when needed. section only when needed.
@header{wx/thread.h}
@sa wxThread, wxMutex, @ref overview_thread @sa wxThread, wxMutex, @ref overview_thread

9
interface/arrstr.h
View File

@@ -350,6 +350,8 @@ public:
separators. separators.
@see wxJoin() @see wxJoin()
@header{wx/arrstr.h}
*/ */
wxArrayString wxSplit(const wxString& str, const wxChar sep, wxArrayString wxSplit(const wxString& str, const wxChar sep,
const wxChar escape = '\\'); 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 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 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 which is necessary in order to be able to recover the original array
from the string later using wxSplit(). contents from the string later using wxSplit().
@see wxSplit() @see wxSplit()
@header{wx/arrstr.h}
*/ */
wxString wxJoin(const wxArrayString& arr, const wxChar sep, wxString wxJoin(const wxArrayString& arr, const wxChar sep,
const wxChar escape = '\\'); const wxChar escape = '\\');
//@} //@}

65
interface/chartype.h
View File

@@ -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 This macro can be used with character and string literals (in other words,
words, @c 'x' or @c "foo") to automatically convert them to Unicode in @c 'x' or @c "foo") to automatically convert them to Unicode in Unicode
Unicode build configuration. Please see the builds of wxWidgets. This macro is simply returns the value passed to it
@ref overview_unicode "Unicode overview" for more information. without changes in ASCII build. In fact, its definition is:
This macro is simply returns the value passed to it without changes in ASCII
build. In fact, its definition is:
@code @code
#ifdef UNICODE #ifdef UNICODE
#define wxT(x) L ## x # define wxT(x) L ## x
#else // !Unicode #else // !Unicode
#define wxT(x) x # define wxT(x) x
#endif #endif
@endcode @endcode
@see @ref overview_unicode
@header{wx/chartype.h}
*/ */
wxChar wxT(char ch); #define wxT(string)
const wxChar* wxT(const char* s);
//@}
//@{
/** /**
wxS is macro which can be used with character and string literals to either 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 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 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 optional as the translation will always be done at run-time even if there
mismatch between the kind of the literal used and wxStringCharType used in the is a mismatch between the kind of the literal used and string or character
current build, but using it can be beneficial in performance-sensitive code to type used in the current build, but using it can be beneficial in
do the conversion at compile-time instead. performance-sensitive code to do the conversion at compile-time instead.
@see wxT() @see wxT()
*/
wxStringCharType wxS(char ch);
const wxStringCharType* wxS(const char* s);
//@}
@header{wx/chartype.h}
*/
#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)
//@}

155
interface/intl.h
View File

@@ -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().
*/
#define const wxString wxPLURAL(const wxString& sing,
const wxString& plur,
size_t n) /* implementation is private */
/** /**
This macro doesn't do anything in the program code -- it simply expands to the This macro is identical to _() but for the plural variant of
value of its argument. wxGetTranslation().
@returns A const wxString.
@header{wx/intl.h}
*/
#define wxPLURAL(string, plural, n)
/**
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 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 extraction into the message catalog created by @c xgettext program. Usually
this is achieved using _() but that macro not only marks this is achieved using _() but that macro not only marks the string for
the string for extraction but also expands into a extraction but also expands into a wxGetTranslation() call which means that
wxGetTranslation() function call which means that it it cannot be used in some situations, notably for static array
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 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 static array of strings containing the weekday names and which have to be
translated (note that it is a bad example, really, as translated (note that it is a bad example, really, as wxDateTime already
wxDateTime already can be used to get the localized week can be used to get the localized week day names already). If you write:
day names already). If you write
@code @code
static const char * const weekdays[] = { _("Mon"), ..., _("Sun") }; static const char * const weekdays[] = { _("Mon"), ..., _("Sun") };
@@ -567,8 +572,8 @@ size_t n) /* implementation is private */
// use weekdays[n] as usual // use weekdays[n] as usual
@endcode @endcode
the code wouldn't compile because the function calls are forbidden in the array The code wouldn't compile because the function calls are forbidden in the
initializer. So instead you should do array initializer. So instead you should do this:
@code @code
static const char * const weekdays[] = { wxTRANSLATE("Mon"), ..., static const char * const weekdays[] = { wxTRANSLATE("Mon"), ...,
@@ -577,60 +582,80 @@ size_t n) /* implementation is private */
// use wxGetTranslation(weekdays[n]) // use wxGetTranslation(weekdays[n])
@endcode @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 wxTRANSLATE() in the above, it wouldn't work as expected because there
no translations for the weekday names in the program message catalog and would be no translations for the weekday names in the program message
wxGetTranslation wouldn't find them. 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() This function returns the translation of @a string in the current
function, so it marks the message for the extraction by @c xgettext just as @c locale(). If the string is not found in any of the loaded message
wxTRANSLATE() does, but also returns the translation of catalogs (see @ref overview_i18n), the original string is returned. In
the string for the current locale during execution. debug build, an error message is logged -- this should help to find the
Don't confuse this macro with _T()! 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
const wxString _(const wxString& s); 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().
/**
This function returns the translation of string @a str in the current @note This function is not suitable for literal strings in Unicode builds
locale(). If the string is not found in any of the loaded since the literal strings must be enclosed into _T() or wxT() macro
message catalogs (see @ref overview_internationalization "internationalization which makes them unrecognised by @c xgettext, and so they are not
overview"), the extracted to the message catalog. Instead, use the _() and wxPLURAL()
original string is returned. In debug build, an error message is logged -- this macro for all literal strings.
should help to find the strings which were not yet translated. If
@a domain is specified then only that domain/catalog is searched @see wxGetTranslation(const wxString&, const wxString&, size_t, const wxString&)
for a matching string. As this function
is used very often, an alternative (and also common in Unix world) syntax is @header{wx/intl.h}
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.
*/ */
const wxString wxGetTranslation(const wxString& str, const wxString wxGetTranslation(const wxString& string,
const wxString& domain = wxEmptyString); const wxString& domain = wxEmptyString);
const wxString wxGetTranslation(const wxString& str,
const wxString& strPlural, /**
size_t n, 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& string,
const wxString& plural, size_t n,
const wxString& domain = wxEmptyString); 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);
//@} //@}

29
interface/stopwatch.h
View File

@@ -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.
@see wxDateTime::Now
*/
long wxGetUTCTime();
/** /**
Returns the number of milliseconds since local time 00:00:00 Jan 1st 1970. Returns the number of milliseconds since local time 00:00:00 Jan 1st 1970.
@see wxDateTime::Now, wxLongLong @see wxDateTime::Now(), wxLongLong
@header{wx/stopwatch.h}
*/ */
wxLongLong wxGetLocalTimeMillis(); wxLongLong wxGetLocalTimeMillis();
/**
Returns the number of seconds since GMT 00:00:00 Jan 1st 1970.
@see wxDateTime::Now()
@header{wx/stopwatch.h}
*/
long wxGetUTCTime();
//@}

130
interface/thread.h
View File

@@ -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.
*/
bool wxIsMainThread();
/** /**
This macro combines wxCRIT_SECT_DECLARE() and This macro declares a (static) critical section object named @a cs if
wxCRIT_SECT_LOCKER(): it creates a static critical @c wxUSE_THREADS is 1 and does nothing if it is 0.
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: @header{wx/thread.h}
*/
#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 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 @code
int IncCount() 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 Note that this example assumes that the function is called the first time
thread so that the critical section object is initialized correctly by the time from the main thread so that the critical section object is initialized
other threads start calling it, if this is not the case this approach can correctly by the time other threads start calling it, if this is not the
@b not be used and the critical section must be made a global instead). 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 This macro is equivalent to
@c wxUSE_THREADS is 1 and does nothing if it is 0. As it doesn't @ref wxCriticalSection::Leave "critical_section.Leave()" if
include the @c static keyword (unlike @c wxUSE_THREADS is 1 and does nothing if it is 0.
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(cs) /* implementation is private */ #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}
*/
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 wants to get access to the GUI library. This function will block the
of the calling thread until the main thread (or any other thread holding the execution of the calling thread until the main thread (or any other thread
main GUI lock) leaves the GUI library and no other thread will enter the GUI holding the main GUI lock) leaves the GUI library and no other thread will
library until the calling thread calls ::wxMutexGuiLeave. enter the GUI library until the calling thread calls wxMutexGuiLeave().
Typically, these functions are used like this: Typically, these functions are used like this:
@code @code
void MyThread::Foo(void) void MyThread::Foo(void)
{ {
// before doing any GUI calls we must ensure that this thread is the only // before doing any GUI calls we must ensure that
// one doing it! // 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 This function is only defined on platforms which support preemptive
threads. 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 This function is only defined on platforms which support preemptive
@c wxUSE_THREADS is 1 and does nothing if it is 0. threads.
*/
#define wxCRIT_SECT_DECLARE(cs) /* implementation is private */
/** @see wxMutexGuiEnter()
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 */
/** @header{wx/thread.h}
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.
*/ */
#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 */

533
interface/utils.h
View File

@@ -426,45 +426,38 @@ wxString wxStripMenuCodes(const wxString& str, int flags = wxStrip_All);
/** @ingroup group_funcmacro_networkuseros */
//@{
/** /**
This function returns the "user id" also known as "login name" under Unix Copies the user's email address into the supplied buffer, by concatenating
i.e. something like "jsmith". It uniquely identifies the current user (on the values returned by wxGetFullHostName() and wxGetUserId().
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.
@return Returns the login name if successful or an empty string otherwise. @returns @true if successful, @false otherwise.
@see wxGetUserName()
@header{wx/utils.h} @header{wx/utils.h}
*/ */
wxString wxGetUserId(); wxString wxGetEmailAddress();
/** /**
@deprecated @deprecated Use wxGetEmailAddress() instead.
This form is deprecated, use wxGetUserId() version that returns wxString.
@param buf Buffer to store login name in. @param buf Buffer to store the email address in.
@param sz Size of the buffer. @param sz Size of the buffer.
@return Returns @true if successful, @false otherwise. @returns @true if successful, @false otherwise.
*/
bool wxGetUserId(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.
@see ::wxGetOsVersion
@header{wx/utils.h} @header{wx/utils.h}
*/ */
wxString wxGetOsDescription(); 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. Return the (current) user's home directory.
@@ -476,43 +469,33 @@ wxString wxGetOsDescription();
wxString wxGetHomeDir(); wxString wxGetHomeDir();
/** /**
Sleeps for the specified number of milliseconds. Notice that usage of this Copies the current host machine's name into the supplied buffer. Please
function is encouraged instead of calling usleep(3) directly because the note that the returned name is @e not fully qualified, i.e. it does not
standard usleep() function is not MT safe. 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}
*/ */
void wxMilliSleep(unsigned long milliseconds); wxString wxGetHostName();
/** /**
Sleeps for the specified number of microseconds. The microsecond resolution may @deprecated Use wxGetHostName() instead.
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 @param buf Buffer to store the host name in.
wxMilliSleep()(@e microseconds/1000). @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 wxGetHostName(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".
@header{wx/utils.h}
*/
bool wxShell(const wxString& command = NULL);
/**
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}
*/
wxOperatingSystemId wxGetOsVersion(int* major = NULL,
int* minor = NULL);
/** /**
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
@@ -524,110 +507,218 @@ wxOperatingSystemId wxGetOsVersion(int* major = NULL,
*/ */
wxString wxGetFullHostName(); wxString wxGetFullHostName();
/**
Returns the amount of free memory in bytes under environments which
support it, and -1 if not supported or failed to perform measurement.
*/
wxMemorySize wxGetFreeMemory();
//@{
/**
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.
@see wxGetFullHostName()
@header{wx/utils.h}
*/
wxString wxGetHostName();
bool wxGetHostName(char* buf, int sz);
//@}
/** /**
Returns the home directory for the given user. If the @a user is empty Returns the home directory for the given user. If the @a user is empty
(default value), this function behaves like (default value), this function behaves like wxGetHomeDir() (i.e. returns
wxGetHomeDir() i.e. returns the current user home the current user home directory).
directory.
If the home directory couldn't be determined, an empty string is returned. If the home directory couldn't be determined, an empty string is returned.
@header{wx/utils.h} @header{wx/utils.h}
*/ */
wxString wxGetUserHome(const wxString& user = ""); wxString wxGetUserHome(const wxString& user = "");
//@{
/** /**
@b wxPerl note: In wxPerl this function is called @c Wx::ExecuteStdoutStderr This function returns the "user id" also known as "login name" under Unix
and it only takes the @c command argument, (i.e. something like "jsmith"). It uniquely identifies the current user (on
and returns a 3-element list @c ( status, output, errors ), where this system). Under Windows or NT, this function first looks in the
@c output and @c errors are array references. 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}
*/
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);
/**
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}
*/
wxString wxGetUserName();
/**
@deprecated Use wxGetUserName() instead.
@param buf Buffer to store the full user name in.
@param sz Size of the buffer.
@returns @true if successful, @false otherwise.
@header{wx/utils.h}
*/
bool wxGetUserName(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
"Windows NT Version 4.0" or "Linux 2.2.2 i386".
@see wxGetOsVersion()
@header{wx/utils.h}
*/
wxString wxGetOsDescription();
/**
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}
*/
wxOperatingSystemId wxGetOsVersion(int* major = NULL, int* minor = NULL);
/**
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}
*/
bool wxIsPlatform64Bit();
/**
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}
*/
bool wxIsPlatformLittleEndian();
//@}
/** @ingroup group_funcmacro_procctrl */
//@{
/**
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 In the overloaded versions of this function, if @a flags parameter contains
arguments, terminated by @NULL. @c wxEXEC_ASYNC flag (the default), flow of control immediately returns. If
The semantics of the third and fourth versions is different from the first two it contains @c wxEXEC_SYNC, the current application waits until the other
and is described in more details below. program has terminated.
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 the process (which terminates by the moment the function returns) and will
-1 if the process couldn't be started and typically 0 if the process be -1 if the process couldn't be started and typically 0 if the process
terminated successfully. Also, while waiting for the process to terminated successfully. Also, while waiting for the process to terminate,
terminate, wxExecute will call wxYield(). Because of this, by wxExecute() will call wxYield(). Because of this, by default this function
default this function disables all application windows to avoid unexpected disables all application windows to avoid unexpected reentrancies which
reentrancies which could result from the users interaction with the program could result from the users interaction with the program while the child
while the child process is running. If you are sure that it is safe to not process is running. If you are sure that it is safe to not disable the
disable the program windows, you may pass @c wxEXEC_NODISABLE flag to program windows, you may pass @c wxEXEC_NODISABLE flag to prevent this
prevent this automatic disabling from happening. automatic disabling from happening.
For asynchronous execution, however, the return value is the process id and 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 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 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 launch a new process, but connected to the running one (this can only
case of using DDE under Windows for command execution). In particular, in this, happen when using DDE under Windows for command execution). In particular,
and only this, case the calling code will not get the notification about 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 If @a callback isn't @NULL and if execution is asynchronous,
the process finishes. Specifying this parameter also allows you to redirect the wxProcess::OnTerminate() will be called when the process finishes.
standard input and/or output of the process being launched by calling Specifying this parameter also allows you to redirect the standard input
wxProcess::Redirect. If the child process IO is redirected, and/or output of the process being launched by calling
under Windows the process window is not shown by default (this avoids having to wxProcess::Redirect(). If the child process IO is redirected, under Windows
flush an unnecessary console for the processes which don't create any 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. happening, i.e. with this flag the child process window will be shown
Under Unix the flag @c wxEXEC_MAKE_GROUP_LEADER may be used to ensure normally.
that the new process is a group leader (this will create a new session if
needed). Calling wxKill() passing wxKILL_CHILDREN will Under Unix the flag @c wxEXEC_MAKE_GROUP_LEADER may be used to ensure that
kill this process as well as all of its children (except those which have the new process is a group leader (this will create a new session if
started their own session). 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 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 place while the child process is running. It should be only used for very
short-lived processes as otherwise the application windows risk becoming short-lived processes as otherwise the application windows risk becoming
unresponsive from the users point of view. As this flag only makes sense with unresponsive from the users point of view. As this flag only makes sense
@c wxEXEC_SYNC, @c wxEXEC_BLOCK equal to the sum of both of these flags with @c wxEXEC_SYNC, @c wxEXEC_BLOCK equal to the sum of both of these
is provided as a convenience. 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 @note Currently wxExecute() can only be used from the main thread, calling
@c wxEXEC_SYNC) and capture its output in the array @e output. The this function from another thread will result in an assert failure in
fourth version adds the possibility to additionally capture the messages from debug build and won't work.
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.
@param command @param command
The command to execute and any parameters to pass to it as a The command to execute and any parameters to pass to it as a single
single string. 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 The command to execute should be the first element of this array, any
array, any additional ones are the command parameters and the array must be additional ones are the command parameters and the array must be
terminated with a @NULL pointer. terminated with a @NULL pointer.
@param flags @param flags
Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include 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 wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
their combination, in wxEXEC_SYNC case. their combination, in wxEXEC_SYNC case.
@param callback @param callback
An optional pointer to wxProcess An optional pointer to wxProcess.
@see wxShell(), wxProcess, @ref overview_sampleexec "Exec sample".
@header{wx/utils.h} @header{wx/utils.h}
*/ */
long wxExecute(const wxString& command, long wxExecute(char** argv, int flags = wxEXEC_ASYNC,
int sync = wxEXEC_ASYNC,
wxProcess* callback = NULL); wxProcess* callback = NULL);
long wxExecute(char** argv, long wxExecute(wchar_t** argv, int flags = wxEXEC_ASYNC,
int flags = wxEXEC_ASYNC,
wxProcess* callback = NULL); 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);
//@} //@}
/** @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. This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
The check is performed at run-time and may differ from the value available at please see its documentation for general information.
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 This version adds the possibility to additionally capture the messages from
system standard error output in the @a errors array.
(bi-architecture operating system).
Very important: this function is not 100% reliable on some systems given the @param command
fact The command to execute and any parameters to pass to it as a single
that there isn't always a standard way to do a reliable check on the OS string.
architecture. @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,7 +792,7 @@ 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 @code
enum wxSignal enum wxSignal
@@ -716,11 +816,12 @@ unsigned long wxGetProcessId();
}; };
@endcode @endcode
@c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning under
under both Unix and Windows but all the other signals are equivalent to 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 @code
enum wxKillError enum wxKillError
@@ -733,32 +834,79 @@ unsigned long wxGetProcessId();
}; };
@endcode @endcode
The @a flags parameter can be wxKILL_NOCHILDREN (the default), The @a flags parameter can be wxKILL_NOCHILDREN (the default), or
or wxKILL_CHILDREN, in which case the child processes of this wxKILL_CHILDREN, in which case the child processes of this process will be
process will be killed too. Note that under Unix, for wxKILL_CHILDREN killed too. Note that under Unix, for wxKILL_CHILDREN to work you should
to work you should have created the process by passing wxEXEC_MAKE_GROUP_LEADER have created the process by passing wxEXEC_MAKE_GROUP_LEADER to
to wxExecute. 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 wxKill(long pid, int sig = wxSIGTERM,
int flags = 0); wxKillError rc = NULL, int flags = 0);
//@{
/** /**
Copies the user's email address into the supplied buffer, by Executes a command in an interactive shell window. If no command is
concatenating the values returned by wxGetFullHostName() specified, then just the shell is spawned.
and wxGetUserId().
Returns @true if successful, @false otherwise. @see wxExecute(), @ref page_samples_exec
@header{wx/utils.h} @header{wx/utils.h}
*/ */
wxString wxGetEmailAddress(); bool wxShell(const wxString& command = NULL);
bool wxGetEmailAddress(char* buf, int sz);
/**
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 @deprecated This function is deprecated because its name is misleading:
endian). notice that the argument is in milliseconds, not microseconds.
The check is performed at run-time. 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);
//@}

182
interface/wxcrt.h
View File

@@ -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);
/** /**
@b NB: This function is obsolete, use wxString instead. @returns @true if the pointer is either @NULL or points to an empty string,
A macro defined as: @false otherwise.
@code @header{wx/wxcrt.h}
#define wxStringEq(s1, s2) (s1 && s2 && (strcmp(s1, s2) == 0))
@endcode
*/
bool wxStringEq(const wxString& s1, const wxString& s2);
/**
@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.
*/
bool wxStringMatch(const wxString& s1, const wxString& s2,
bool subString = true,
bool exact = false);
/**
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.
@see wxVsnprintf(), wxString::Printf
*/
int wxSnprintf(wxChar* buf, size_t len, const wxChar* format,
...);
/**
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.
*/
wxArrayString wxStringTokenize(const wxString& str,
const wxString& delims = wxDEFAULT_DELIMITERS,
wxStringTokenizerMode mode = wxTOKEN_DEFAULT);
/**
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.
*/
size_t wxStrlen(const char* p);
/**
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
*/
int wxVsnprintf(wxChar* buf, size_t len, const wxChar* format,
va_list argPtr);
/**
Returns @true if the pointer is either @NULL or points to an empty
string, @false otherwise.
*/ */
bool wxIsEmpty(const char* p); bool wxIsEmpty(const char* p);
/** /**
Returns a negative value, 0, or positive value if @a p1 is less than, equal This is a safe version of standard function @e strlen(): it does exactly
to or greater than @e p2. The comparison is case-insensitive. the same thing (i.e. returns the length of the string) except that it
returns 0 if @a p is the @NULL pointer.
@header{wx/wxcrt.h}
*/
size_t wxStrlen(const char* p);
/**
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}
*/
int wxStrcmp(const char* p1, const char* p2);
/**
This function complements the standard C function @e strcmp() which performs This function complements the standard C function @e strcmp() which performs
case-sensitive comparison. 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.
@header{wx/wxcrt.h}
*/ */
int wxStricmp(const char* p1, const char* p2); int wxStricmp(const char* p1, const char* p2);
/**
@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}
*/
bool wxStringEq(const wxString& s1, const wxString& s2);
/**
@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}
*/
bool wxStringMatch(const wxString& s1, const wxString& s2,
bool subString = true, bool exact = false);
/**
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}
*/
wxArrayString wxStringTokenize(const wxString& string,
const wxString& delims = wxDEFAULT_DELIMITERS,
wxStringTokenizerMode mode = wxTOKEN_DEFAULT);
/**
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}
*/
int wxSnprintf(wxChar* buf, size_t len, const wxChar* format, ...);
/**
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 wxVsnprintf(wxChar* buf, size_t len,
const wxChar* format, va_list argPtr);
//@}