// 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
- 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") };
// 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"), ...,
// 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()!
+ 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);
+
//@}
+/** @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}
*/
-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.
- @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}
*/
-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}
*/
-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}
*/
-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}
*/
-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}
*/
-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}
*/
-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}
*/
-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}
*/
-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}
*/
-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.
- 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
- 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
- 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.
- 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
- 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
- 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
- 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
- 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
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}
*/
-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}
*/
-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.
/**
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
{
- wxSIGNONE = 0, // verify if the process exists under Unix
+ wxSIGNONE = 0, // verify if the process exists under Unix
wxSIGHUP,
wxSIGINT,
wxSIGQUIT,
wxSIGABRT,
wxSIGEMT,
wxSIGFPE,
- wxSIGKILL, // forcefully kill, dangerous!
+ wxSIGKILL, // forcefully kill, dangerous!
wxSIGBUS,
wxSIGSEGV,
wxSIGSYS,
wxSIGPIPE,
wxSIGALRM,
- wxSIGTERM // terminate the process gently
+ wxSIGTERM // terminate the process gently
};
@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.
- 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
{
- 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
- 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}
*/
-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}
*/
-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.
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}
*/
-bool wxIsPlatformLittleEndian();
+void wxUsleep(unsigned long milliseconds);
+
+//@}
// 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);
+
+//@}
projects / wxWidgets.git / commitdiff
