Version: 3.0.5
Loading...
Searching...
No Matches
utils.h File Reference

Classes

class  wxWindowDisabler
 This class disables all windows of the application (may be with the exception of one of them) in its constructor and enables them back in its destructor. More...
 
class  wxBusyCursor
 This class makes it easy to tell your user that the program is temporarily busy. More...
 
struct  wxExecuteEnv
 This structure can optionally be passed to wxExecute() to specify additional options to use for the child process. More...
 

Typedefs

typedef wxStringToStringHashMap wxEnvVariableHashMap
 A map type containing environment variables names and values.
 
typedef int(* wxSortCallback) (const void *pItem1, const void *pItem2, const void *user_data)
 Compare function type for use with wxQsort()
 

Enumerations

enum  wxSignal {
  wxSIGNONE = 0 ,
  wxSIGHUP ,
  wxSIGINT ,
  wxSIGQUIT ,
  wxSIGILL ,
  wxSIGTRAP ,
  wxSIGABRT ,
  wxSIGEMT ,
  wxSIGFPE ,
  wxSIGKILL ,
  wxSIGBUS ,
  wxSIGSEGV ,
  wxSIGSYS ,
  wxSIGPIPE ,
  wxSIGALRM ,
  wxSIGTERM
}
 Signal constants used by wxProcess. More...
 
enum  wxKillError {
  wxKILL_OK ,
  wxKILL_BAD_SIGNAL ,
  wxKILL_ACCESS_DENIED ,
  wxKILL_NO_PROCESS ,
  wxKILL_ERROR
}
 Return values for wxProcess::Kill. More...
 
enum  wxKillFlags {
  wxKILL_NOCHILDREN = 0 ,
  wxKILL_CHILDREN = 1
}
 
enum  wxShutdownFlags {
  wxSHUTDOWN_FORCE = 1 ,
  wxSHUTDOWN_POWEROFF = 2 ,
  wxSHUTDOWN_REBOOT = 4 ,
  wxSHUTDOWN_LOGOFF = 8
}
 
enum  {
  wxStrip_Mnemonics = 1 ,
  wxStrip_Accel = 2 ,
  wxStrip_All = wxStrip_Mnemonics | wxStrip_Accel
}
 flags for wxStripMenuCodes More...
 
enum  {
  wxEXEC_ASYNC = 0 ,
  wxEXEC_SYNC = 1 ,
  wxEXEC_SHOW_CONSOLE = 2 ,
  wxEXEC_MAKE_GROUP_LEADER = 4 ,
  wxEXEC_NODISABLE = 8 ,
  wxEXEC_NOEVENTS = 16 ,
  wxEXEC_HIDE_CONSOLE = 32 ,
  wxEXEC_BLOCK = wxEXEC_SYNC | wxEXEC_NOEVENTS
}
 Bit flags that can be used with wxExecute(). More...
 

Functions

void wxBeginBusyCursor (const wxCursor *cursor=wxHOURGLASS_CURSOR)
 Changes the cursor to the given cursor for all windows in the application.
 
void wxEndBusyCursor ()
 Changes the cursor back to the original cursor, for all windows in the application.
 
bool wxIsBusy ()
 Returns true if between two wxBeginBusyCursor() and wxEndBusyCursor() calls.
 
void wxBell ()
 Ring the system bell.
 
void wxInfoMessageBox (wxWindow *parent)
 Shows a message box with the information about the wxWidgets build used, including its version, most important build parameters and the version of the underlying GUI toolkit.
 
wxVersionInfo wxGetLibraryVersionInfo ()
 Get wxWidgets version information.
 
wxCharwxGetenv (const wxString &var)
 This is a macro defined as getenv() or its wide char version in Unicode mode.
 
bool wxGetEnv (const wxString &var, wxString *value)
 Returns the current value of the environment variable var in value.
 
bool wxSetEnv (const wxString &var, const wxString &value)
 Sets the value of the environment variable var (adding it if necessary) to value.
 
bool wxUnsetEnv (const wxString &var)
 Removes the variable var from the environment.
 
bool wxGetEnvMap (wxEnvVariableHashMap *map)
 Fill a map with the complete content of current environment.
 
wxBatteryState wxGetBatteryState ()
 Returns battery state as one of wxBATTERY_NORMAL_STATE, wxBATTERY_LOW_STATE, wxBATTERY_CRITICAL_STATE, wxBATTERY_SHUTDOWN_STATE or wxBATTERY_UNKNOWN_STATE.
 
wxPowerType wxGetPowerType ()
 Returns the type of power source as one of wxPOWER_SOCKET, wxPOWER_BATTERY or wxPOWER_UNKNOWN.
 
wxString wxGetDisplayName ()
 Under X only, returns the current display name.
 
bool wxGetKeyState (wxKeyCode key)
 For normal keys, returns true if the specified key is currently down.
 
wxPoint wxGetMousePosition ()
 Returns the mouse position in screen coordinates.
 
wxMouseState wxGetMouseState ()
 Returns the current state of the mouse.
 
void wxEnableTopLevelWindows (bool enable=true)
 This function enables or disables all top level windows.
 
wxWindowwxFindWindowAtPoint (const wxPoint &pt)
 Find the deepest window at the given mouse position in screen coordinates, returning the window if found, or NULL if not.
 
wxWindowwxFindWindowByLabel (const wxString &label, wxWindow *parent=NULL)
 
wxWindowwxFindWindowByName (const wxString &name, wxWindow *parent=NULL)
 
int wxFindMenuItemId (wxFrame *frame, const wxString &menuString, const wxString &itemString)
 Find a menu item identifier associated with the given frame's menu bar.
 
int wxNewId ()
 
void wxRegisterId (int id)
 Ensures that Ids subsequently generated by wxNewId() do not clash with the given id.
 
bool wxLaunchDefaultApplication (const wxString &document, int flags=0)
 Opens the document in the application associated with the files of this type.
 
bool wxLaunchDefaultBrowser (const wxString &url, int flags=0)
 Opens the url in user's default browser.
 
bool wxLoadUserResource (const void **outData, size_t *outLen, const wxString &resourceName, const wxChar *resourceType="TEXT", WXHINSTANCE module=0)
 Loads an object from Windows resource file.
 
char * wxLoadUserResource (const wxString &resourceName, const wxChar *resourceType="TEXT", int *pLen=NULL, WXHINSTANCE module=0)
 Loads a user-defined Windows resource as a string.
 
void wxPostDelete (wxObject *object)
 
void wxQsort (void *pbase, size_t total_elems, size_t size, wxSortCallback cmp, const void *user_data)
 Function implementing quick sort algorithm.
 
void wxSetDisplayName (const wxString &displayName)
 Under X only, sets the current display name.
 
wxString wxStripMenuCodes (const wxString &str, int flags=wxStrip_All)
 Strips any menu codes from str and returns the result.
 
wxString wxGetEmailAddress ()
 Copies the user's email address into the supplied buffer, by concatenating the values returned by wxGetFullHostName() and wxGetUserId().
 
bool wxGetEmailAddress (char *buf, int sz)
 
wxMemorySize wxGetFreeMemory ()
 Returns the amount of free memory in bytes under environments which support it, and -1 if not supported or failed to perform measurement.
 
wxString wxGetHomeDir ()
 Return the (current) user's home directory.
 
wxString wxGetHostName ()
 Copies the current host machine's name into the supplied buffer.
 
bool wxGetHostName (char *buf, int sz)
 
wxString wxGetFullHostName ()
 Returns the FQDN (fully qualified domain host name) or an empty string on error.
 
wxString wxGetUserHome (const wxString &user=wxEmptyString)
 Returns the home directory for the given user.
 
wxString wxGetUserId ()
 This function returns the "user id" also known as "login name" under Unix (i.e.
 
bool wxGetUserId (char *buf, int sz)
 
wxString wxGetUserName ()
 This function returns the full user name (something like "Mr. John Smith").
 
bool wxGetUserName (char *buf, int sz)
 
wxString wxGetOsDescription ()
 Returns the string containing the description of the current platform in a user-readable form.
 
wxOperatingSystemId wxGetOsVersion (int *major=NULL, int *minor=NULL)
 Gets the version and the operating system ID for currently running OS.
 
bool wxIsPlatform64Bit ()
 Returns true if the operating system the program is running under is 64 bit.
 
bool wxIsPlatformLittleEndian ()
 Returns true if the current platform is little endian (instead of big endian).
 
wxLinuxDistributionInfo wxGetLinuxDistributionInfo ()
 Returns a structure containing information about the currently running Linux distribution.
 
long wxExecute (const wxString &command, int flags=wxEXEC_ASYNC, wxProcess *callback=NULL, const wxExecuteEnv *env=NULL)
 Executes another program in Unix or Windows.
 
long wxExecute (char **argv, int flags=wxEXEC_ASYNC, wxProcess *callback=NULL, const wxExecuteEnv *env=NULL)
 This is an overloaded version of wxExecute(const wxString&,int,wxProcess*), please see its documentation for general information.
 
long wxExecute (wchar_t **argv, int flags=wxEXEC_ASYNC, wxProcess *callback=NULL, const wxExecuteEnv *env=NULL)
 
long wxExecute (const wxString &command, wxArrayString &output, int flags=0, const wxExecuteEnv *env=NULL)
 This is an overloaded version of wxExecute(const wxString&,int,wxProcess*), please see its documentation for general information.
 
long wxExecute (const wxString &command, wxArrayString &output, wxArrayString &errors, int flags=0, const wxExecuteEnv *env=NULL)
 This is an overloaded version of wxExecute(const wxString&,int,wxProcess*), please see its documentation for general information.
 
unsigned long wxGetProcessId ()
 Returns the number uniquely identifying the current process in the system.
 
int wxKill (long pid, wxSignal sig=wxSIGTERM, wxKillError *rc=NULL, int flags=wxKILL_NOCHILDREN)
 Equivalent to the Unix kill function: send the given signal sig to the process with PID pid.
 
bool wxShell (const wxString &command=wxEmptyString)
 Executes a command in an interactive shell window.
 
bool wxShutdown (int flags=wxSHUTDOWN_POWEROFF)
 This function shuts down or reboots the computer depending on the value of the flags.
 
void wxMicroSleep (unsigned long microseconds)
 Sleeps for the specified number of microseconds.
 
void wxMilliSleep (unsigned long milliseconds)
 Sleeps for the specified number of milliseconds.
 
wxString wxNow ()
 Returns a string representing the current date and time.
 
void wxSleep (int secs)
 Sleeps for the specified number of seconds.
 
void wxUsleep (unsigned long milliseconds)
 

Typedef Documentation

◆ wxEnvVariableHashMap

typedef wxStringToStringHashMap wxEnvVariableHashMap

A map type containing environment variables names and values.

This type is used with wxGetEnvMap() function and wxExecuteEnv structure optionally passed to wxExecute().

Since
2.9.2

Include file:

#include <wx/utils.h> 

◆ wxSortCallback

typedef int(* wxSortCallback) (const void *pItem1, const void *pItem2, const void *user_data)

Compare function type for use with wxQsort()

Include file:

#include <wx/utils.h> 

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

flags for wxStripMenuCodes

Enumerator
wxStrip_Mnemonics 
wxStrip_Accel 
wxStrip_All 

◆ anonymous enum

anonymous enum

Bit flags that can be used with wxExecute().

Enumerator
wxEXEC_ASYNC 

Execute the process asynchronously.

Notice that, due to its value, this is the default.

wxEXEC_SYNC 

Execute the process synchronously.

wxEXEC_SHOW_CONSOLE 

Always show the child process console under MSW.

The child console is hidden by default if the child IO is redirected, this flag allows changing this and showing it nevertheless.

This flag is ignored under the other platforms.

wxEXEC_MAKE_GROUP_LEADER 

Make the new process a group leader.

Under Unix, if the process is the group leader then passing wxKILL_CHILDREN to wxKill() kills all children as well as pid.

Under MSW, applies only to console applications and is only supported under NT family (i.e. not under Windows 9x). It corresponds to the native CREATE_NEW_PROCESS_GROUP and, in particular, ensures that Ctrl-Break signals will be sent to all children of this process as well to the process itself. Support for this flag under MSW was added in version 2.9.4 of wxWidgets.

wxEXEC_NODISABLE 

Don't disable the program UI while running the child synchronously.

By default synchronous execution disables all program windows to avoid that the user interacts with the program while the child process is running, you can use this flag to prevent this from happening.

This flag can only be used with wxEXEC_SYNC.

wxEXEC_NOEVENTS 

Don't dispatch events while the child process is executed.

By default, the event loop is run while waiting for synchronous execution to complete and this flag can be used to simply block the main process until the child process finishes

This flag can only be used with wxEXEC_SYNC.

wxEXEC_HIDE_CONSOLE 

Hide child process console under MSW.

Under MSW, hide the console of the child process if it has one, even if its IO is not redirected.

This flag is ignored under the other platforms.

wxEXEC_BLOCK 

Convenient synonym for flags given system()-like behaviour.

◆ wxKillError

Return values for wxProcess::Kill.

Enumerator
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

◆ wxKillFlags

Enumerator
wxKILL_NOCHILDREN 

don't kill children

wxKILL_CHILDREN 

kill children

◆ wxShutdownFlags

Enumerator
wxSHUTDOWN_FORCE 

can be combined with other flags (MSW-only)

wxSHUTDOWN_POWEROFF 

power off the computer

wxSHUTDOWN_REBOOT 

shutdown and reboot

wxSHUTDOWN_LOGOFF 

close session (currently MSW-only)

◆ wxSignal

enum wxSignal

Signal constants used by wxProcess.

Enumerator
wxSIGNONE 

verify if the process exists under Unix

wxSIGHUP 
wxSIGINT 
wxSIGQUIT 
wxSIGILL 
wxSIGTRAP 
wxSIGABRT 
wxSIGEMT 
wxSIGFPE 
wxSIGKILL 

forcefully kill, dangerous!

wxSIGBUS 
wxSIGSEGV 
wxSIGSYS 
wxSIGPIPE 
wxSIGALRM 
wxSIGTERM 

terminate the process gently

Function Documentation

◆ wxBeginBusyCursor()

void wxBeginBusyCursor ( const wxCursor cursor = wxHOURGLASS_CURSOR)

Changes the cursor to the given cursor for all windows in the application.

Use wxEndBusyCursor() to revert the cursor back to its previous state. These two calls can be nested, and a counter ensures that only the outer calls take effect.

See also
wxIsBusy(), wxBusyCursor

Include file:

#include <wx/utils.h> 

◆ wxBell()

void wxBell ( )

Ring the system bell.

Note
This function is categorized as a GUI one and so is not thread-safe.

Include file:

#include <wx/utils.h> 

Library:  wxCore

◆ wxEnableTopLevelWindows()

void wxEnableTopLevelWindows ( bool  enable = true)

This function enables or disables all top level windows.

It is used by wxSafeYield().

Include file:

#include <wx/utils.h> 

◆ wxEndBusyCursor()

void wxEndBusyCursor ( )

Changes the cursor back to the original cursor, for all windows in the application.

Use with wxBeginBusyCursor().

See also
wxIsBusy(), wxBusyCursor

Include file:

#include <wx/utils.h> 

◆ wxExecute() [1/5]

long wxExecute ( char **  argv,
int  flags = wxEXEC_ASYNC,
wxProcess callback = NULL,
const wxExecuteEnv env = NULL 
)

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.

Parameters
argvThe 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.
flagsSame as for wxExecute(const wxString&,int,wxProcess*) overload.
callbackAn optional pointer to wxProcess.
envAn optional pointer to additional parameters for the child process, such as its initial working directory and environment variables. This parameter is available in wxWidgets 2.9.2 and later only.
See also
wxShell(), wxProcess, External Program Execution Sample, wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()

Include file:

#include <wx/utils.h> 

wxPerl Note: In wxPerl this function is called Wx::ExecuteArgs.

◆ wxExecute() [2/5]

long wxExecute ( const wxString command,
int  flags = wxEXEC_ASYNC,
wxProcess callback = NULL,
const wxExecuteEnv env = NULL 
)

Executes another program in Unix or Windows.

In the overloaded versions of this function, if flags parameter contains wxEXEC_ASYNC flag (the default), flow of control immediately returns. If it contains 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 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 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().

Under Windows, when launching a console process its console is shown by default but hidden if its IO is redirected. Both of these default behaviours may be overridden: if wxEXEC_HIDE_CONSOLE is specified, the console will never be shown. If wxEXEC_SHOW_CONSOLE is used, the console will be shown even if the child process IO is redirected. Neither of these flags affect non-console Windows applications or does anything under the other systems.

Under Unix the flag 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). Under MSW, this flag can be used with console processes only and corresponds to the native CREATE_NEW_PROCESS_GROUP flag.

The 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 wxEXEC_SYNC, 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.
Parameters
commandThe command to execute and any parameters to pass to it as a single string, i.e. "emacs file.txt".
flagsMust include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include wxEXEC_SHOW_CONSOLE, wxEXEC_HIDE_CONSOLE, 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.
callbackAn optional pointer to wxProcess.
envAn optional pointer to additional parameters for the child process, such as its initial working directory and environment variables. This parameter is available in wxWidgets 2.9.2 and later only.
See also
wxShell(), wxProcess, External Program Execution Sample, wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()

Include file:

#include <wx/utils.h> 

wxPerl Note: In wxPerl this function is called Wx::ExecuteCommand.

◆ wxExecute() [3/5]

long wxExecute ( const wxString command,
wxArrayString output,
int  flags = 0,
const wxExecuteEnv env = NULL 
)

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 flags is or'd with wxEXEC_SYNC) and capture its output in the array output.

Parameters
commandThe command to execute and any parameters to pass to it as a single string.
outputThe string array where the stdout of the executed process is saved.
flagsCombination of flags to which wxEXEC_SYNC is always implicitly added.
envAn optional pointer to additional parameters for the child process, such as its initial working directory and environment variables. This parameter is available in wxWidgets 2.9.2 and later only.
See also
wxShell(), wxProcess, External Program Execution Sample, wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()

Include file:

#include <wx/utils.h> 

wxPerl Note: This function is called Wx::ExecuteStdout: it only takes the command argument, and returns a 2-element list (status, output), where output in an array reference.

◆ wxExecute() [4/5]

long wxExecute ( const wxString command,
wxArrayString output,
wxArrayString errors,
int  flags = 0,
const wxExecuteEnv env = NULL 
)

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 errors array. As with the above overload capturing standard output only, execution is always synchronous.

Parameters
commandThe command to execute and any parameters to pass to it as a single string.
outputThe string array where the stdout of the executed process is saved.
errorsThe string array where the stderr of the executed process is saved.
flagsCombination of flags to which wxEXEC_SYNC is always implicitly added.
envAn optional pointer to additional parameters for the child process, such as its initial working directory and environment variables. This parameter is available in wxWidgets 2.9.2 and later only.
See also
wxShell(), wxProcess, External Program Execution Sample, wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()

Include file:

#include <wx/utils.h> 

wxPerl Note: This function is called Wx::ExecuteStdoutStderr: it only takes the command argument, and returns a 3-element list (status, output, errors), where output and errors are array references.

◆ wxExecute() [5/5]

long wxExecute ( wchar_t **  argv,
int  flags = wxEXEC_ASYNC,
wxProcess callback = NULL,
const wxExecuteEnv env = NULL 
)

◆ wxFindMenuItemId()

int wxFindMenuItemId ( wxFrame frame,
const wxString menuString,
const wxString itemString 
)

Find a menu item identifier associated with the given frame's menu bar.

Include file:

#include <wx/utils.h> 

◆ wxFindWindowAtPoint()

wxWindow * wxFindWindowAtPoint ( const wxPoint pt)

Find the deepest window at the given mouse position in screen coordinates, returning the window if found, or NULL if not.

This function takes child windows at the given position into account even if they are disabled. The hidden children are however skipped by it.

Include file:

#include <wx/utils.h> 

◆ wxFindWindowByLabel()

wxWindow * wxFindWindowByLabel ( const wxString label,
wxWindow parent = NULL 
)
Deprecated:
Replaced by wxWindow::FindWindowByLabel().

Find a window by its label. Depending on the type of window, the label may be a window title or panel item label. If parent is NULL, the search will start from all top-level frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy. The search is recursive in both cases.

Include file:

#include <wx/utils.h> 

◆ wxFindWindowByName()

wxWindow * wxFindWindowByName ( const wxString name,
wxWindow parent = NULL 
)
Deprecated:
Replaced by wxWindow::FindWindowByName().

Find a window by its name (as given in a window constructor or Create function call). If parent is NULL, the search will start from all top-level frames and dialog boxes; if non-NULL, the search will be limited to the given window hierarchy. The search is recursive in both cases.

If no such named window is found, wxFindWindowByLabel() is called.

Include file:

#include <wx/utils.h> 

◆ wxGetBatteryState()

wxBatteryState wxGetBatteryState ( )

Returns battery state as one of wxBATTERY_NORMAL_STATE, wxBATTERY_LOW_STATE, wxBATTERY_CRITICAL_STATE, wxBATTERY_SHUTDOWN_STATE or wxBATTERY_UNKNOWN_STATE.

wxBATTERY_UNKNOWN_STATE is also the default on platforms where this feature is not implemented (currently everywhere but MS Windows).

Include file:

#include <wx/utils.h> 

◆ wxGetDisplayName()

wxString wxGetDisplayName ( )

Under X only, returns the current display name.

See also
wxSetDisplayName()

Include file:

#include <wx/utils.h> 

◆ wxGetEmailAddress() [1/2]

wxString wxGetEmailAddress ( )

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.

Include file:

#include <wx/utils.h> 

◆ wxGetEmailAddress() [2/2]

bool wxGetEmailAddress ( char *  buf,
int  sz 
)
Deprecated:
Use wxGetEmailAddress() instead.
Parameters
bufBuffer to store the email address in.
szSize of the buffer.
Returns
true if successful, false otherwise.

Include file:

#include <wx/utils.h> 

◆ wxGetenv()

wxChar * wxGetenv ( const wxString var)

This is a macro defined as getenv() or its wide char version in Unicode mode.

Note that under Win32 it may not return correct value for the variables set with wxSetEnv(), use wxGetEnv() function instead.

Include file:

#include <wx/utils.h> 

◆ wxGetEnv()

bool wxGetEnv ( const wxString var,
wxString value 
)

Returns the current value of the environment variable var in value.

value may be NULL if you just want to know if the variable exists and are not interested in its value.

Returns true if the variable exists, false otherwise.

Include file:

#include <wx/utils.h> 

◆ wxGetEnvMap()

bool wxGetEnvMap ( wxEnvVariableHashMap map)

Fill a map with the complete content of current environment.

The map will contain the environment variable names as keys and their values as values.

Parameters
mapThe environment map to fill, must be non-NULL.
Returns
true if environment was successfully retrieved or false otherwise.

Include file:

#include <wx/utils.h> 
Since
2.9.2

◆ wxGetFreeMemory()

wxMemorySize wxGetFreeMemory ( )

Returns the amount of free memory in bytes under environments which support it, and -1 if not supported or failed to perform measurement.

Include file:

#include <wx/utils.h> 

◆ wxGetFullHostName()

wxString wxGetFullHostName ( )

Returns the FQDN (fully qualified domain host name) or an empty string on error.

See also
wxGetHostName()

Include file:

#include <wx/utils.h> 

◆ wxGetHomeDir()

wxString wxGetHomeDir ( )

Return the (current) user's home directory.

See also
wxGetUserHome(), wxStandardPaths

Include file:

#include <wx/utils.h> 

◆ wxGetHostName() [1/2]

wxString wxGetHostName ( )

Copies the current host machine's name into the supplied buffer.

Please note that the returned name is 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 HostName in the wxWidgets section of the WIN.INI file is tried.

Returns
The hostname if successful or an empty string otherwise.
See also
wxGetFullHostName()

Include file:

#include <wx/utils.h> 

◆ wxGetHostName() [2/2]

bool wxGetHostName ( char *  buf,
int  sz 
)
Deprecated:
Use wxGetHostName() instead.
Parameters
bufBuffer to store the host name in.
szSize of the buffer.
Returns
true if successful, false otherwise.

Include file:

#include <wx/utils.h> 

◆ wxGetKeyState()

bool wxGetKeyState ( wxKeyCode  key)

For normal keys, returns true if the specified key is currently down.

For togglable keys (Caps Lock, Num Lock and Scroll Lock), returns true if the key is toggled such that its LED indicator is lit. There is currently no way to test whether togglable keys are up or down.

Even though there are virtual key codes defined for mouse buttons, they cannot be used with this function currently.

In wxGTK, this function can be only used with modifier keys (WXK_ALT, WXK_CONTROL and WXK_SHIFT) when not using X11 backend currently.

Include file:

#include <wx/utils.h> 

◆ wxGetLibraryVersionInfo()

wxVersionInfo wxGetLibraryVersionInfo ( )

Get wxWidgets version information.

Since
2.9.2
See also
wxVersionInfo

Include file:

#include <wx/utils.h> 

Library:  wxCore

◆ wxGetLinuxDistributionInfo()

wxLinuxDistributionInfo wxGetLinuxDistributionInfo ( )

Returns a structure containing information about the currently running Linux distribution.

This function uses the lsb_release utility which is part of the Linux Standard Base Core specification (see http://refspecs.linux-foundation.org/lsb.shtml) since the very first LSB release 1.0 (released in 2001). The lsb_release utility is very common on modern Linux distributions but in case it's not available, then this function will return a wxLinuxDistributionInfo structure containing empty strings.

This function is Linux-specific and is only available when the __LINUX__ symbol is defined.

◆ wxGetMousePosition()

wxPoint wxGetMousePosition ( )

Returns the mouse position in screen coordinates.

Include file:

#include <wx/utils.h> 

◆ wxGetMouseState()

wxMouseState wxGetMouseState ( )

Returns the current state of the mouse.

Returns a wxMouseState instance that contains the current position of the mouse pointer in screen coordinates, as well as boolean values indicating the up/down status of the mouse buttons and the modifier keys.

Include file:

#include <wx/utils.h> 

◆ wxGetOsDescription()

wxString wxGetOsDescription ( )

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 also
wxGetOsVersion()

Include file:

#include <wx/utils.h> 

◆ wxGetOsVersion()

wxOperatingSystemId wxGetOsVersion ( int *  major = NULL,
int *  minor = NULL 
)

Gets the version and the operating system ID for currently running OS.

The returned wxOperatingSystemId value can be used for a basic categorization of the OS family; the major and minor version numbers allows detecting a specific system.

For Unix-like systems (wxOS_UNIX) the major and minor version integers will contain the kernel major and minor version numbers (as returned by the 'uname -r' command); e.g. "2" and "6" if the machine is using kernel 2.6.19.

For Mac OS X systems (wxOS_MAC) the major and minor version integers are the natural version numbers associated with the OS; e.g. "10" and "6" if the machine is using Mac OS X Snow Leopard.

For Windows-like systems (wxOS_WINDOWS) the major and minor version integers will contain the following values:

Windows OS name Major version Minor version
Windows 7 6 1
Windows Server 2008 R2 6 1
Windows Server 2008 6 0
Windows Vista 6 0
Windows Server 2003 R2 5 2
Windows Server 2003 5 2
Windows XP 5 1
Windows 2000 5 0

See the MSDN for more info about the values above.

See also
wxGetOsDescription(), wxPlatformInfo

Include file:

#include <wx/utils.h> 

◆ wxGetPowerType()

wxPowerType wxGetPowerType ( )

Returns the type of power source as one of wxPOWER_SOCKET, wxPOWER_BATTERY or wxPOWER_UNKNOWN.

wxPOWER_UNKNOWN is also the default on platforms where this feature is not implemented (currently everywhere but MS Windows).

Include file:

#include <wx/utils.h> 

◆ wxGetProcessId()

unsigned long wxGetProcessId ( )

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

If an error occurs, 0 is returned.

Include file:

#include <wx/utils.h> 

◆ wxGetUserHome()

wxString wxGetUserHome ( const wxString user = wxEmptyString)

Returns the home directory for the given user.

If the 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.

Include file:

#include <wx/utils.h> 

◆ wxGetUserId() [1/2]

wxString wxGetUserId ( )

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 UserId in the wxWidgets section of the WIN.INI file is tried.

Returns
The login name if successful or an empty string otherwise.
See also
wxGetUserName()

Include file:

#include <wx/utils.h> 

◆ wxGetUserId() [2/2]

bool wxGetUserId ( char *  buf,
int  sz 
)
Deprecated:
Use wxGetUserId() instead.
Parameters
bufBuffer to store the login name in.
szSize of the buffer.
Returns
true if successful, false otherwise.

Include file:

#include <wx/utils.h> 

◆ wxGetUserName() [1/2]

wxString wxGetUserName ( )

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 also
wxGetUserId()

Include file:

#include <wx/utils.h> 

◆ wxGetUserName() [2/2]

bool wxGetUserName ( char *  buf,
int  sz 
)
Deprecated:
Use wxGetUserName() instead.
Parameters
bufBuffer to store the full user name in.
szSize of the buffer.
Returns
true if successful, false otherwise.

Include file:

#include <wx/utils.h> 

◆ wxInfoMessageBox()

void wxInfoMessageBox ( wxWindow parent)

Shows a message box with the information about the wxWidgets build used, including its version, most important build parameters and the version of the underlying GUI toolkit.

This is mainly used for diagnostic purposes and can be invoked by Ctrl-Alt-middle clicking on any wxWindow which doesn't otherwise handle this event.

Since
2.9.0
See also
wxGetLibraryVersionInfo()

Include file:

#include <wx/utils.h> 

◆ wxIsBusy()

bool wxIsBusy ( )

Returns true if between two wxBeginBusyCursor() and wxEndBusyCursor() calls.

See also
wxBusyCursor.

Include file:

#include <wx/utils.h> 

◆ wxIsPlatform64Bit()

bool wxIsPlatform64Bit ( )

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 sizeof(void*) == 8) 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.

Include file:

#include <wx/utils.h> 

◆ wxIsPlatformLittleEndian()

bool wxIsPlatformLittleEndian ( )

Returns true if the current platform is little endian (instead of big endian).

The check is performed at run-time.

See also
Byte Order Functions and Macros

Include file:

#include <wx/utils.h> 

◆ wxKill()

int wxKill ( long  pid,
wxSignal  sig = wxSIGTERM,
wxKillError rc = NULL,
int  flags = wxKILL_NOCHILDREN 
)

Equivalent to the Unix kill function: send the given signal sig to the process with PID pid.

The valid signal values are:

{
wxSIGNONE = 0, // verify if the process exists under Unix
wxSIGKILL, // forcefully kill, dangerous!
wxSIGTERM // terminate the process gently
};
wxSignal
Signal constants used by wxProcess.
Definition utils.h:12
@ wxSIGILL
Definition utils.h:17
@ wxSIGPIPE
Definition utils.h:26
@ wxSIGFPE
Definition utils.h:21
@ wxSIGTRAP
Definition utils.h:18
@ wxSIGQUIT
Definition utils.h:16
@ wxSIGBUS
Definition utils.h:23
@ wxSIGABRT
Definition utils.h:19
@ wxSIGSEGV
Definition utils.h:24
@ wxSIGEMT
Definition utils.h:20
@ wxSIGSYS
Definition utils.h:25
@ wxSIGALRM
Definition utils.h:27
@ wxSIGTERM
terminate the process gently
Definition utils.h:28
@ wxSIGNONE
verify if the process exists under Unix
Definition utils.h:13
@ wxSIGINT
Definition utils.h:15
@ wxSIGKILL
forcefully kill, dangerous!
Definition utils.h:22
@ wxSIGHUP
Definition utils.h:14

wxSIGNONE, wxSIGKILL and wxSIGTERM have the same meaning under both Unix and Windows but all the other signals are equivalent to wxSIGTERM under Windows. Moreover, under Windows, wxSIGTERM is implemented by posting a message to the application window, so it only works if the application does have windows. If it doesn't, as is notably always the case for the console applications, you need to use wxSIGKILL to actually kill the process. Of course, this doesn't allow the process to shut down gracefully and so should be avoided if possible.

Returns 0 on success, -1 on failure. If the rc parameter is not NULL, it will be filled with a value from the wxKillError enum:

{
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
};
wxKillError
Return values for wxProcess::Kill.
Definition utils.h:35
@ wxKILL_BAD_SIGNAL
no such signal
Definition utils.h:37
@ wxKILL_ERROR
another, unspecified error
Definition utils.h:40
@ wxKILL_NO_PROCESS
no such process
Definition utils.h:39
@ wxKILL_OK
no error
Definition utils.h:36
@ wxKILL_ACCESS_DENIED
permission denied
Definition utils.h:38

The 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 also
wxProcess::Kill(), wxProcess::Exists(), External Program Execution Sample

Include file:

#include <wx/utils.h> 

◆ wxLaunchDefaultApplication()

bool wxLaunchDefaultApplication ( const wxString document,
int  flags = 0 
)

Opens the document in the application associated with the files of this type.

The flags parameter is currently not used

Returns true if the application was successfully launched.

See also
wxLaunchDefaultBrowser(), wxExecute()

Include file:

#include <wx/utils.h> 

◆ wxLaunchDefaultBrowser()

bool wxLaunchDefaultBrowser ( const wxString url,
int  flags = 0 
)

Opens the url in user's default browser.

If the flags parameter contains wxBROWSER_NEW_WINDOW flag, a new window is opened for the URL (currently this is only supported under Windows).

And unless the flags parameter contains wxBROWSER_NOBUSYCURSOR flag, a busy cursor is shown while the browser is being launched (using wxBusyCursor).

The parameter url is interpreted as follows:

  • if it has a valid scheme (e.g. "file:", "http:" or "mailto:") it is passed to the appropriate browser configured in the user system.
  • if it has no valid scheme (e.g. it's a local file path without the "file:" prefix), then wxFileExists and wxDirExists are used to test if it's a local file/directory; if it is, then the browser is called with the url parameter eventually prefixed by "file:".
  • if it has no valid scheme and it's not a local file/directory, then "http:" is prepended and the browser is called.

Returns true if the application was successfully launched.

Note
For some configurations of the running user, the application which is launched to open the given URL may be URL-dependent (e.g. a browser may be used for local URLs while another one may be used for remote URLs).
See also
wxLaunchDefaultApplication(), wxExecute()

Include file:

#include <wx/utils.h> 

◆ wxLoadUserResource() [1/2]

bool wxLoadUserResource ( const void **  outData,
size_t *  outLen,
const wxString resourceName,
const wxChar resourceType = "TEXT",
WXHINSTANCE  module = 0 
)

Loads an object from Windows resource file.

This function loads the resource with the given name and type from the resources embedded into a Windows application.

The typical use for it is to load some data from the data files embedded into the program itself. For example, you could have the following fragment in your .rc file

mydata MYDATA "myfile.dat"

and then use it in the following way:

const void* data = NULL;
size_t size = 0;
if ( !wxLoadUserResource(&data, &size, "mydata", "MYDATA") ) {
... handle error ...
}
else {
// Use the data in any way, for example:
wxMemoryInputStream is(data, size);
... read the data from stream ...
}
This class allows using all methods taking a wxInputStream reference to read in-memory data.
Definition mstream.h:99
bool wxLoadUserResource(const void **outData, size_t *outLen, const wxString &resourceName, const wxChar *resourceType="TEXT", WXHINSTANCE module=0)
Loads an object from Windows resource file.
Parameters
outDataFilled with the pointer to the data on successful return. Notice that this pointer does not need to be freed by the caller.
outLenFilled with the length of the data in bytes.
resourceNameThe name of the resource to load.
resourceTypeThe type of the resource in usual Windows format, i.e. either a real string like "MYDATA" or an integer created by the standard Windows MAKEINTRESOURCE() macro, including any constants for the standard resources types like RT_RCDATA.
moduleThe HINSTANCE of the module to load the resources from. The current module is used by default.
Returns
true if the data was loaded from resource or false if it couldn't be found (in which case no error is logged) or was found but couldn't be loaded (which is unexpected and does result in an error message).

This function is available under Windows only.

Library:  wxBase

Include file:

#include <wx/utils.h> 
Since
2.9.1

◆ wxLoadUserResource() [2/2]

char * wxLoadUserResource ( const wxString resourceName,
const wxChar resourceType = "TEXT",
int *  pLen = NULL,
WXHINSTANCE  module = 0 
)

Loads a user-defined Windows resource as a string.

This is a wrapper for the general purpose overload wxLoadUserResource(const void**, size_t*, const wxString&, const wxChar*, WXHINSTANCE) and can be more convenient for the string data, but does an extra copy compared to the general version.

Parameters
resourceNameThe name of the resource to load.
resourceTypeThe type of the resource in usual Windows format, i.e. either a real string like "MYDATA" or an integer created by the standard Windows MAKEINTRESOURCE() macro, including any constants for the standard resources types like RT_RCDATA.
pLenFilled with the length of the returned buffer if it is non-NULL. This parameter should be used if NUL characters can occur in the resource data. It is new since wxWidgets 2.9.1
moduleThe HINSTANCE of the module to load the resources from. The current module is used by default. This parameter is new since wxWidgets 2.9.1.
Returns
A pointer to the data to be delete[]d by caller on success or NULL on error.

This function is available under Windows only.

Library:  wxBase

Include file:

#include <wx/utils.h> 

◆ wxMicroSleep()

void wxMicroSleep ( unsigned long  microseconds)

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 microseconds/1000.

Include file:

#include <wx/utils.h> 

◆ wxMilliSleep()

void wxMilliSleep ( unsigned long  milliseconds)

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.

Include file:

#include <wx/utils.h> 

◆ wxNewId()

int wxNewId ( )
Deprecated:
Ids generated by it can conflict with the Ids defined by the user code, use wxID_ANY to assign ids which are guaranteed to not conflict with the user-defined ids for the controls and menu items you create instead of using this function.

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

Include file:

#include <wx/utils.h> 

◆ wxNow()

wxString wxNow ( )

Returns a string representing the current date and time.

Include file:

#include <wx/utils.h> 

◆ wxPostDelete()

void wxPostDelete ( wxObject object)
Deprecated:
Replaced by wxWindow::Close(). See the window deletion overview.

Tells the system to delete the specified object when all other events have been processed. In some environments, it is necessary to use this instead of deleting a frame directly with the delete operator, because some GUIs will still send events to a deleted window.

Include file:

#include <wx/utils.h> 

◆ wxQsort()

void wxQsort ( void *  pbase,
size_t  total_elems,
size_t  size,
wxSortCallback  cmp,
const void *  user_data 
)

Function implementing quick sort algorithm.

This function sorts total_elems objects of size size located at pbase. It uses cmp function for comparing them and passes user_data pointer to the comparison function each time it's called.

Include file:

#include <wx/utils.h> 

◆ wxRegisterId()

void wxRegisterId ( int  id)

Ensures that Ids subsequently generated by wxNewId() do not clash with the given id.

Include file:

#include <wx/utils.h> 

◆ wxSetDisplayName()

void wxSetDisplayName ( const wxString displayName)

Under X only, sets the current display name.

This is the X host and display name such as "colonsay:0.0", and the function indicates which display should be used for creating windows from this point on. Setting the display within an application allows multiple displays to be used.

See also
wxGetDisplayName()

Include file:

#include <wx/utils.h> 

◆ wxSetEnv()

bool wxSetEnv ( const wxString var,
const wxString value 
)

Sets the value of the environment variable var (adding it if necessary) to value.

Notice that under Windows platforms the program may have two different environment blocks: the first one is that of a Windows process and is always present, but the CRT may maintain its own independent copy of the environment. wxSetEnv() will always update the first copy, which means that wxGetEnv(), which uses it directly, will always return the expected value after this call. But wxSetEnv() only updates the second copy for some compilers/CRT implementations (currently only MSVC and MinGW which uses the same MSVC CRT) and so using wxGetenv() (notice the difference in case) may not return the updated value.

Parameters
varThe environment variable to be set, must not contain '=' character.
valueNew value of the variable.
Returns
true on success or false if changing the value failed.
See also
wxUnsetEnv()

Include file:

#include <wx/utils.h> 

◆ wxShell()

bool wxShell ( const wxString command = wxEmptyString)

Executes a command in an interactive shell window.

If no command is specified, then just the shell is spawned.

See also
wxExecute(), External Program Execution Sample

Include file:

#include <wx/utils.h> 

◆ wxShutdown()

bool wxShutdown ( int  flags = wxSHUTDOWN_POWEROFF)

This function shuts down or reboots the computer depending on the value of the flags.

Note
Note that performing the shutdown requires the corresponding access rights (superuser under Unix, SE_SHUTDOWN privilege under Windows NT) and that this function is only implemented under Unix and MSW.
Parameters
flagsOne of wxSHUTDOWN_POWEROFF, wxSHUTDOWN_REBOOT or wxSHUTDOWN_LOGOFF (currently implemented only for MSW) possibly combined with wxSHUTDOWN_FORCE which forces shutdown under MSW by forcefully terminating all the applications. As doing this can result in a data loss, this flag shouldn't be used unless really necessary.
Returns
true on success, false if an error occurred.

Include file:

#include <wx/utils.h> 

◆ wxSleep()

void wxSleep ( int  secs)

Sleeps for the specified number of seconds.

Include file:

#include <wx/utils.h> 

◆ wxStripMenuCodes()

wxString wxStripMenuCodes ( const wxString str,
int  flags = wxStrip_All 
)

Strips any menu codes from str and returns the result.

By default, the functions strips both the mnemonics character ('&') which is used to indicate a keyboard shortkey, and the accelerators, which are used only in the menu items and are separated from the main text by the \t (TAB) character. By using flags of wxStrip_Mnemonics or wxStrip_Accel to strip only the former or the latter part, respectively.

Notice that in most cases wxMenuItem::GetLabelFromText() or wxControl::GetLabelText() can be used instead.

Include file:

#include <wx/utils.h> 

◆ wxUnsetEnv()

bool wxUnsetEnv ( const wxString var)

Removes the variable var from the environment.

wxGetEnv() will return NULL after the call to this function.

Returns true on success.

Include file:

#include <wx/utils.h> 

◆ wxUsleep()

void wxUsleep ( unsigned long  milliseconds)
Deprecated:
This function is deprecated because its name is misleading: notice that the argument is in milliseconds, not microseconds. Please use either wxMilliSleep() or wxMicroSleep() depending on the resolution you need.

Sleeps for the specified number of milliseconds.

Include file:

#include <wx/utils.h>