Mirrors_UI_SDK/wxWidgets
1
0
Fork 0
mirror of https://github.com/wxWidgets/wxWidgets.git synced 2026-09-26 18:18:26 +08:00
Code Issues Actions 1 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
docs/doxygen/groups/funcmacro_thread.h
+5 -7
View File
@@ -11,17 +11,15 @@
@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,
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
interface/arrstr.h
+7 -2
View File
@@ -350,6 +350,8 @@ public:
separators.
@see wxJoin()
@header{wx/arrstr.h}
*/
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
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()
@header{wx/arrstr.h}
*/
wxString wxJoin(const wxArrayString& arr, const wxChar sep,
const wxChar escape = '\\');
//@}
interface/chartype.h
+39 -26
View File
@@ -6,41 +6,54 @@
// 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:
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
@code
#ifdef UNICODE
# define wxT(x) L ## x
#else // !Unicode
# define wxT(x) x
#endif
@endcode
@see @ref overview_unicode
@header{wx/chartype.h}
*/
wxChar wxT(char ch);
const wxChar* wxT(const char* s);
//@}
#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
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()
*/
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)
//@}
interface/intl.h
+92 -67
View File
@@ -537,29 +537,34 @@ public:
// Global functions/macros
// ============================================================================
/**
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 */
/** @ingroup group_funcmacro_string */
//@{
/**
This macro doesn't do anything in the program code -- it simply expands to the
value of its argument.
This macro is identical to _() but for the plural variant of
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
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.
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") };
@@ -567,8 +572,8 @@ size_t n) /* implementation is private */
// 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"), ...,
@@ -577,60 +582,80 @@ size_t n) /* implementation is private */
// use wxGetTranslation(weekdays[n])
@endcode
here.
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()!
*/
const wxString _(const wxString& s);
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 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 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 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& domain = wxEmptyString);
/**
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);
/**
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);
//@}
interface/stopwatch.h
+20 -9
View File
@@ -72,24 +72,35 @@ public:
// Global functions/macros
// ============================================================================
/** @ingroup group_funcmacro_time */
//@{
/**
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();
/**
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.
@see wxDateTime::Now, wxLongLong
@see wxDateTime::Now(), wxLongLong
@header{wx/stopwatch.h}
*/
wxLongLong wxGetLocalTimeMillis();
/**
Returns the number of seconds since GMT 00:00:00 Jan 1st 1970.
@see wxDateTime::Now()
@header{wx/stopwatch.h}
*/
long wxGetUTCTime();
//@}
interface/thread.h
+82 -48
View File
@@ -926,17 +926,41 @@ public:
// Global functions/macros
// ============================================================================
/**
Returns @true if this thread is the main one. Always returns @true if
@c wxUSE_THREADS is 0.
*/
bool wxIsMainThread();
/** @ingroup group_funcmacro_thread */
//@{
/**
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 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}
*/
#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
int IncCount()
@@ -949,35 +973,56 @@ bool wxIsMainThread();
}
@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 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
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)
{
// 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();
@@ -988,36 +1033,25 @@ bool wxIsMainThread();
}
@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.
@note Under GTK, no creation of top-level windows is allowed in any thread
but the main one.
@header{wx/thread.h}
*/
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 */
//@}
interface/utils.h
+352 -201
View File
File diff suppressed because it is too large Load Diff
interface/wxcrt.h
+103 -79
View File
@@ -6,94 +6,118 @@
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
/**
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);
/** @ingroup group_funcmacro_string */
//@{
/**
@b NB: This function is obsolete, use wxString instead.
A macro defined as:
@returns @true if the pointer is either @NULL or points to an empty string,
@false otherwise.
@code
#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.
@header{wx/wxcrt.h}
*/
bool wxIsEmpty(const char* p);
/**
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 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.
@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
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);
/**
@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);
//@}