1519 lines
47 KiB
Objective-C
1519 lines
47 KiB
Objective-C
/////////////////////////////////////////////////////////////////////////////
|
||
// Name: utils.h
|
||
// Purpose: interface of various utility classes and functions
|
||
// Author: wxWidgets team
|
||
// Licence: wxWindows licence
|
||
/////////////////////////////////////////////////////////////////////////////
|
||
|
||
/**
|
||
Signal constants used by wxProcess.
|
||
*/
|
||
enum wxSignal
|
||
{
|
||
wxSIGNONE = 0, //!< 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
|
||
};
|
||
|
||
/**
|
||
Return values for wxProcess::Kill.
|
||
*/
|
||
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
|
||
};
|
||
|
||
enum wxKillFlags
|
||
{
|
||
wxKILL_NOCHILDREN = 0, //!< don't kill children
|
||
wxKILL_CHILDREN = 1 //!< kill children
|
||
};
|
||
|
||
enum wxShutdownFlags
|
||
{
|
||
wxSHUTDOWN_FORCE = 1, //!< can be combined with other flags (MSW-only)
|
||
wxSHUTDOWN_POWEROFF = 2, //!< power off the computer
|
||
wxSHUTDOWN_REBOOT = 4, //!< shutdown and reboot
|
||
wxSHUTDOWN_LOGOFF = 8 //!< close session (currently MSW-only)
|
||
};
|
||
|
||
|
||
/**
|
||
@class wxWindowDisabler
|
||
|
||
This class disables all top level windows of the application (maybe with
|
||
the exception of one of them) in its constructor and enables them back in
|
||
its destructor.
|
||
|
||
This is useful when you want to indicate to the user that the application
|
||
is currently busy and cannot respond to user input.
|
||
|
||
@note When instantiated, this affects only windows shown on the screen and
|
||
not already disabled.
|
||
|
||
@library{wxcore}
|
||
@category{misc}
|
||
|
||
@see wxBusyCursor
|
||
*/
|
||
class wxWindowDisabler
|
||
{
|
||
public:
|
||
/**
|
||
Disables all top level windows of the applications.
|
||
|
||
If @a disable is @c false nothing is done. This can be convenient if
|
||
the windows should be disabled depending on some condition.
|
||
|
||
@since 2.9.0
|
||
*/
|
||
wxWindowDisabler(bool disable = true);
|
||
|
||
/**
|
||
Disables all top level windows of the applications with the exception
|
||
of @a winToSkip if it is not @NULL.
|
||
|
||
Notice that under MSW if @a winToSkip appears in the taskbar, the user
|
||
will be able to close the entire application (even though its main
|
||
window is disabled) by right clicking on the taskbar icon and selecting
|
||
the appropriate "Close" command from the context menu. To prevent this
|
||
from happening you may want to use wxFRAME_TOOL_WINDOW, if applicable,
|
||
or wxFRAME_NO_TASKBAR style when creating the window that will remain
|
||
enabled.
|
||
*/
|
||
wxWindowDisabler(wxWindow* winToSkip);
|
||
|
||
/**
|
||
Reenables the windows disabled by the constructor.
|
||
*/
|
||
~wxWindowDisabler();
|
||
};
|
||
|
||
|
||
|
||
/**
|
||
@class wxBusyCursor
|
||
|
||
This class makes it easy to tell your user that the program is temporarily
|
||
busy. Just create a wxBusyCursor object on the stack, and within the
|
||
current scope, the hourglass will be shown.
|
||
|
||
For example:
|
||
|
||
@code
|
||
wxBusyCursor wait;
|
||
|
||
for (int i = 0; i < 100000; i++)
|
||
DoACalculation();
|
||
@endcode
|
||
|
||
It works by calling wxBeginBusyCursor() in the constructor, and
|
||
wxEndBusyCursor() in the destructor.
|
||
|
||
@library{wxcore}
|
||
@category{misc}
|
||
|
||
@see wxBeginBusyCursor(), wxEndBusyCursor(), wxWindowDisabler
|
||
*/
|
||
class wxBusyCursor
|
||
{
|
||
public:
|
||
/**
|
||
Constructs a busy cursor object, calling wxBeginBusyCursor().
|
||
*/
|
||
wxBusyCursor(const wxCursor* cursor = wxHOURGLASS_CURSOR);
|
||
|
||
/**
|
||
Destroys the busy cursor object, calling wxEndBusyCursor().
|
||
*/
|
||
~wxBusyCursor();
|
||
};
|
||
|
||
|
||
|
||
// ============================================================================
|
||
// Global functions/macros
|
||
// ============================================================================
|
||
|
||
|
||
/** @addtogroup group_funcmacro_dialog */
|
||
//@{
|
||
|
||
/**
|
||
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 wxIsBusy(), wxBusyCursor
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
void wxBeginBusyCursor(const wxCursor* cursor = wxHOURGLASS_CURSOR);
|
||
|
||
/**
|
||
Changes the cursor back to the original cursor, for all windows in the
|
||
application. Use with wxBeginBusyCursor().
|
||
|
||
@see wxIsBusy(), wxBusyCursor
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
void wxEndBusyCursor();
|
||
|
||
/**
|
||
Returns @true if between two wxBeginBusyCursor() and wxEndBusyCursor()
|
||
calls.
|
||
|
||
@see wxBusyCursor.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
bool wxIsBusy();
|
||
|
||
/**
|
||
Ring the system bell.
|
||
|
||
@note This function is categorized as a GUI one and so is not thread-safe.
|
||
|
||
@header{wx/utils.h}
|
||
|
||
@library{wxcore}
|
||
*/
|
||
void wxBell();
|
||
|
||
/**
|
||
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 wxGetLibraryVersionInfo()
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
void wxInfoMessageBox(wxWindow* parent);
|
||
|
||
//@}
|
||
|
||
/** @addtogroup group_funcmacro_version */
|
||
//@{
|
||
|
||
/**
|
||
Get wxWidgets version information.
|
||
|
||
@since 2.9.2
|
||
|
||
@see wxVersionInfo
|
||
|
||
@header{wx/utils.h}
|
||
|
||
@library{wxcore}
|
||
*/
|
||
wxVersionInfo wxGetLibraryVersionInfo();
|
||
|
||
//@}
|
||
|
||
|
||
|
||
/** @addtogroup group_funcmacro_env */
|
||
//@{
|
||
|
||
/**
|
||
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
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
typedef wxStringToStringHashMap wxEnvVariableHashMap;
|
||
|
||
/**
|
||
This is a macro defined as @c 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.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
wxChar* wxGetenv(const wxString& var);
|
||
|
||
/**
|
||
Returns the current value of the environment variable @a var in @a value.
|
||
|
||
@a 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.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
bool wxGetEnv(const wxString& var, wxString* value);
|
||
|
||
/**
|
||
Sets the value of the environment variable @a var (adding it if necessary)
|
||
to @a 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.
|
||
|
||
@param var
|
||
The environment variable to be set, must not contain @c '=' character.
|
||
@param value
|
||
New value of the variable.
|
||
@return
|
||
@true on success or @false if changing the value failed.
|
||
|
||
@see wxUnsetEnv()
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
bool wxSetEnv(const wxString& var, const wxString& value);
|
||
|
||
/**
|
||
Removes the variable @a var from the environment.
|
||
|
||
wxGetEnv() will return @NULL after the call to this function.
|
||
|
||
Returns @true on success.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
bool wxUnsetEnv(const wxString& var);
|
||
|
||
/**
|
||
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.
|
||
|
||
@param map
|
||
The environment map to fill, must be non-@NULL.
|
||
@return
|
||
@true if environment was successfully retrieved or @false otherwise.
|
||
|
||
@header{wx/utils.h}
|
||
|
||
@since 2.9.2
|
||
*/
|
||
bool wxGetEnvMap(wxEnvVariableHashMap *map);
|
||
//@}
|
||
|
||
|
||
|
||
/** @addtogroup group_funcmacro_misc */
|
||
//@{
|
||
|
||
/**
|
||
Returns battery state as one of @c wxBATTERY_NORMAL_STATE,
|
||
@c wxBATTERY_LOW_STATE, @c wxBATTERY_CRITICAL_STATE,
|
||
@c wxBATTERY_SHUTDOWN_STATE or @c wxBATTERY_UNKNOWN_STATE.
|
||
@c wxBATTERY_UNKNOWN_STATE is also the default on platforms where this
|
||
feature is not implemented (currently everywhere but MS Windows).
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
wxBatteryState wxGetBatteryState();
|
||
|
||
/**
|
||
Returns the type of power source as one of @c wxPOWER_SOCKET,
|
||
@c wxPOWER_BATTERY or @c wxPOWER_UNKNOWN. @c wxPOWER_UNKNOWN is also the
|
||
default on platforms where this feature is not implemented (currently
|
||
everywhere but MS Windows).
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
wxPowerType wxGetPowerType();
|
||
|
||
/**
|
||
Under X only, returns the current display name.
|
||
|
||
@see wxSetDisplayName()
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
wxString wxGetDisplayName();
|
||
|
||
/**
|
||
This function returns the total number of bytes and number of free bytes on
|
||
the disk containing the directory @a path (it should exist). Both @a total
|
||
and @a free parameters may be @NULL if the corresponding information is not
|
||
needed.
|
||
|
||
@since 2.3.2
|
||
|
||
@note The generic Unix implementation depends on the system having the
|
||
@c statfs() or @c statvfs() function.
|
||
|
||
@return @true on success, @false if an error occurred (for example, the
|
||
directory doesn’t exist).
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
bool wxGetDiskSpace(const wxString& path,
|
||
wxLongLong total = NULL,
|
||
wxLongLong free = NULL);
|
||
|
||
/**
|
||
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 (@c WXK_ALT, @c
|
||
WXK_CONTROL and @c WXK_SHIFT) when not using X11 backend currently.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
bool wxGetKeyState(wxKeyCode key);
|
||
|
||
/**
|
||
Returns the mouse position in screen coordinates.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
wxPoint wxGetMousePosition();
|
||
|
||
/**
|
||
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.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
wxMouseState wxGetMouseState();
|
||
|
||
/**
|
||
This function enables or disables all top level windows. It is used by
|
||
wxSafeYield().
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
void wxEnableTopLevelWindows(bool enable = true);
|
||
|
||
/**
|
||
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.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
wxWindow* wxFindWindowAtPoint(const wxPoint& pt);
|
||
|
||
/**
|
||
@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 @a 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.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
wxWindow* wxFindWindowByLabel(const wxString& label,
|
||
wxWindow* parent = NULL);
|
||
|
||
/**
|
||
@deprecated Replaced by wxWindow::FindWindowByName().
|
||
|
||
Find a window by its name (as given in a window constructor or @e Create
|
||
function call). If @a 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.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
wxWindow* wxFindWindowByName(const wxString& name, wxWindow* parent = NULL);
|
||
|
||
/**
|
||
Find a menu item identifier associated with the given frame's menu bar.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
int wxFindMenuItemId(wxFrame* frame, const wxString& menuString,
|
||
const wxString& itemString);
|
||
|
||
/**
|
||
@deprecated Ids generated by it can conflict with the Ids defined by the
|
||
user code, use @c 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.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
int wxNewId();
|
||
|
||
/**
|
||
Ensures that Ids subsequently generated by wxNewId() do not clash with the
|
||
given @a id.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
void wxRegisterId(int id);
|
||
|
||
/**
|
||
Opens the @a document in the application associated with the files of this
|
||
type.
|
||
|
||
The @a flags parameter is currently not used
|
||
|
||
Returns @true if the application was successfully launched.
|
||
|
||
@see wxLaunchDefaultBrowser(), wxExecute()
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
bool wxLaunchDefaultApplication(const wxString& document, int flags = 0);
|
||
|
||
/**
|
||
Opens the @a url in user's default browser.
|
||
|
||
If the @a flags parameter contains @c wxBROWSER_NEW_WINDOW flag, a new
|
||
window is opened for the URL (currently this is only supported under
|
||
Windows).
|
||
|
||
And unless the @a flags parameter contains @c wxBROWSER_NOBUSYCURSOR flag,
|
||
a busy cursor is shown while the browser is being launched (using
|
||
wxBusyCursor).
|
||
|
||
The parameter @a url is interpreted as follows:
|
||
- if it has a valid scheme (e.g. @c "file:", @c "http:" or @c "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 @c "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
|
||
@a url parameter eventually prefixed by @c "file:".
|
||
- if it has no valid scheme and it's not a local file/directory, then @c "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 wxLaunchDefaultApplication(), wxExecute()
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
bool wxLaunchDefaultBrowser(const wxString& url, int flags = 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 @c .rc file
|
||
@code
|
||
mydata MYDATA "myfile.dat"
|
||
@endcode
|
||
and then use it in the following way:
|
||
@code
|
||
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 ...
|
||
}
|
||
@endcode
|
||
|
||
@param outData Filled with the pointer to the data on successful return.
|
||
Notice that this pointer does @em not need to be freed by the caller.
|
||
@param outLen Filled with the length of the data in bytes.
|
||
@param resourceName The name of the resource to load.
|
||
@param resourceType The type of the resource in usual Windows format, i.e.
|
||
either a real string like "MYDATA" or an integer created by the
|
||
standard Windows @c MAKEINTRESOURCE() macro, including any constants
|
||
for the standard resources types like @c RT_RCDATA.
|
||
@param module The @c HINSTANCE of the module to load the resources from.
|
||
The current module is used by default.
|
||
@return 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}
|
||
|
||
@header{wx/utils.h}
|
||
|
||
@since 2.9.1
|
||
*/
|
||
bool
|
||
wxLoadUserResource(const void **outData,
|
||
size_t *outLen,
|
||
const wxString& resourceName,
|
||
const wxChar* resourceType = "TEXT",
|
||
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.
|
||
|
||
@param resourceName The name of the resource to load.
|
||
@param resourceType The type of the resource in usual Windows format, i.e.
|
||
either a real string like "MYDATA" or an integer created by the
|
||
standard Windows @c MAKEINTRESOURCE() macro, including any constants
|
||
for the standard resources types like @c RT_RCDATA.
|
||
@param pLen Filled 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
|
||
@param module The @c 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.
|
||
@return A pointer to the data to be <tt>delete[]</tt>d by caller on success
|
||
or @NULL on error.
|
||
|
||
This function is available under Windows only.
|
||
|
||
@library{wxbase}
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
char* wxLoadUserResource(const wxString& resourceName,
|
||
const wxChar* resourceType = "TEXT",
|
||
int* pLen = NULL,
|
||
WXHINSTANCE module = 0);
|
||
|
||
/**
|
||
@deprecated Replaced by wxWindow::Close(). See the
|
||
@ref overview_windowdeletion "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.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
void wxPostDelete(wxObject* object);
|
||
|
||
|
||
/**
|
||
Compare function type for use with wxQsort()
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
typedef int (*wxSortCallback)(const void* pItem1, const void* pItem2, const void* user_data);
|
||
|
||
/**
|
||
Function implementing quick sort algorithm.
|
||
|
||
This function sorts @a total_elems objects of size @a size located at @a
|
||
pbase. It uses @a cmp function for comparing them and passes @a user_data
|
||
pointer to the comparison function each time it's called.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
void wxQsort(void* pbase, size_t total_elems,
|
||
size_t size, wxSortCallback cmp, const void* user_data);
|
||
|
||
|
||
/**
|
||
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 wxGetDisplayName()
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
void wxSetDisplayName(const wxString& displayName);
|
||
|
||
|
||
/**
|
||
flags for wxStripMenuCodes
|
||
*/
|
||
enum
|
||
{
|
||
// strip '&' characters
|
||
wxStrip_Mnemonics = 1,
|
||
|
||
// strip everything after '\t'
|
||
wxStrip_Accel = 2,
|
||
|
||
// strip everything (this is the default)
|
||
wxStrip_All = wxStrip_Mnemonics | wxStrip_Accel
|
||
};
|
||
|
||
/**
|
||
Strips any menu codes from @a str and returns the result.
|
||
|
||
By default, the functions strips both the mnemonics character (@c '&')
|
||
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
|
||
@c \\t (TAB) character. By using @a flags of @c wxStrip_Mnemonics or
|
||
@c 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.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
wxString wxStripMenuCodes(const wxString& str, int flags = wxStrip_All);
|
||
|
||
//@}
|
||
|
||
|
||
|
||
/** @addtogroup group_funcmacro_networkuseros */
|
||
//@{
|
||
|
||
/**
|
||
Copies the user's email address into the supplied buffer, by concatenating
|
||
the values returned by wxGetFullHostName() and wxGetUserId().
|
||
|
||
@return @true if successful, @false otherwise.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
wxString wxGetEmailAddress();
|
||
|
||
/**
|
||
@deprecated Use wxGetEmailAddress() instead.
|
||
|
||
@param buf Buffer to store the email address in.
|
||
@param sz Size of the buffer.
|
||
|
||
@return @true if successful, @false otherwise.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
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.
|
||
|
||
@return The hostname if successful or an empty string otherwise.
|
||
|
||
@see wxGetFullHostName()
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
wxString wxGetHostName();
|
||
|
||
/**
|
||
@deprecated Use wxGetHostName() instead.
|
||
|
||
@param buf Buffer to store the host name in.
|
||
@param sz Size of the buffer.
|
||
|
||
@return @true if successful, @false otherwise.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
bool wxGetHostName(char* buf, int sz);
|
||
|
||
/**
|
||
Returns the FQDN (fully qualified domain host name) or an empty string on
|
||
error.
|
||
|
||
@see wxGetHostName()
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
wxString wxGetFullHostName();
|
||
|
||
/**
|
||
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.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
wxString wxGetUserHome(const wxString& user = wxEmptyString);
|
||
|
||
/**
|
||
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.
|
||
|
||
@return The login name if successful or an empty string otherwise.
|
||
|
||
@see wxGetUserName()
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
wxString wxGetUserId();
|
||
|
||
/**
|
||
@deprecated Use wxGetUserId() instead.
|
||
|
||
@param buf Buffer to store the login name in.
|
||
@param sz Size of the buffer.
|
||
|
||
@return @true if successful, @false otherwise.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
bool wxGetUserId(char* buf, int sz);
|
||
|
||
/**
|
||
This function returns the full user name (something like "Mr. John Smith").
|
||
|
||
Under Windows or NT, this function looks for the entry UserName in the
|
||
wxWidgets section of the WIN.INI file. If PenWindows is running, the entry
|
||
Current in the section User of the PENWIN.INI file is used.
|
||
|
||
@return The full user name if successful or an empty string otherwise.
|
||
|
||
@see wxGetUserId()
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
wxString wxGetUserName();
|
||
|
||
/**
|
||
@deprecated Use wxGetUserName() instead.
|
||
|
||
@param buf Buffer to store the full user name in.
|
||
@param sz Size of the buffer.
|
||
|
||
@return @true if successful, @false otherwise.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
bool wxGetUserName(char* buf, int sz);
|
||
|
||
/**
|
||
Returns the string containing the description of the current platform in a
|
||
user-readable form. For example, this function may return strings like
|
||
"Windows 10 (build 10240), 64-bit edition" or "Linux 4.1.4 i386".
|
||
|
||
@see wxGetOsVersion()
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
wxString wxGetOsDescription();
|
||
|
||
/**
|
||
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, minor, and micro version numbers allows to
|
||
detect a specific system.
|
||
|
||
If on Unix-like systems the version can't be detected all three version
|
||
numbers will have a value of -1.
|
||
|
||
On systems where only the micro version can't be detected or doesn't make
|
||
sense such as Windows, it will have a value of 0.
|
||
|
||
For Unix-like systems (@c wxOS_UNIX) the major, minor, and micro version
|
||
integers will contain the kernel's major, minor, and micro version
|
||
numbers (as returned by the 'uname -r' command); e.g. "4", "1", and "4" if
|
||
the machine is using kernel 4.1.4.
|
||
|
||
For OS X systems (@c wxOS_MAC) the major and minor version integers are the
|
||
natural version numbers associated with the OS; e.g. "10", "11" and "2" if
|
||
the machine is using OS X El Capitan 10.11.2.
|
||
|
||
For Windows-like systems (@c wxOS_WINDOWS) the major and minor version integers will
|
||
contain the following values:
|
||
@beginTable
|
||
@row3col{<b>Windows OS name</b>, <b>Major version</b>, <b>Minor version</b>}
|
||
@row3col{Windows 10, 10, 0}
|
||
@row3col{Windows Server 2016, 10, 0}
|
||
@row3col{Windows 8.1, 6, 3}
|
||
@row3col{Windows Server 2012 R2, 6, 3}
|
||
@row3col{Windows 8, 6, 2}
|
||
@row3col{Windows Server 2012, 6, 2}
|
||
@row3col{Windows 7, 6, 1}
|
||
@row3col{Windows Server 2008 R2, 6, 1}
|
||
@row3col{Windows Server 2008, 6, 0}
|
||
@row3col{Windows Vista, 6, 0}
|
||
@row3col{Windows Server 2003 R2, 5, 2}
|
||
@row3col{Windows Server 2003, 5, 2}
|
||
@row3col{Windows XP, 5, 1}
|
||
@endDefList
|
||
See the <a href="http://msdn.microsoft.com/en-us/library/ms724832(VS.85).aspx">MSDN</a>
|
||
for more info about the values above.
|
||
|
||
@see wxGetOsDescription(), wxPlatformInfo
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
wxOperatingSystemId wxGetOsVersion(int* major = NULL, int* minor = NULL, int* micro = NULL);
|
||
|
||
/**
|
||
Returns @true if the version of the operating system on which the program
|
||
is running under is the same or later than the given version.
|
||
|
||
@since 3.1.0
|
||
|
||
@see wxGetOsVersion(), wxPlatformInfo
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
bool wxCheckOsVersion(int majorVsn, int minorVsn = 0, int microVsn = 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
|
||
<tt>sizeof(void*) == 8</tt>) since the program could be running in
|
||
emulation mode or in a mixed 32/64 bit system (bi-architecture operating
|
||
system).
|
||
|
||
@note This function is not 100% reliable on some systems given the fact
|
||
that there isn't always a standard way to do a reliable check on the
|
||
OS architecture.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
bool wxIsPlatform64Bit();
|
||
|
||
/**
|
||
Returns @true if the current platform is little endian (instead of big
|
||
endian). The check is performed at run-time.
|
||
|
||
@see @ref group_funcmacro_byteorder "Byte Order Functions and Macros"
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
bool wxIsPlatformLittleEndian();
|
||
|
||
/**
|
||
Returns a structure containing information about the currently running
|
||
Linux distribution.
|
||
|
||
This function uses the @c lsb_release utility which is part of the
|
||
<tt>Linux Standard Base Core</tt> specification
|
||
(see http://refspecs.linux-foundation.org/lsb.shtml) since the very first LSB
|
||
release 1.0 (released in 2001).
|
||
The @c 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 @c __LINUX__
|
||
symbol is defined.
|
||
*/
|
||
wxLinuxDistributionInfo wxGetLinuxDistributionInfo();
|
||
|
||
//@}
|
||
|
||
|
||
|
||
/** @addtogroup group_funcmacro_procctrl */
|
||
//@{
|
||
|
||
/**
|
||
@struct wxExecuteEnv
|
||
|
||
This structure can optionally be passed to wxExecute() to specify
|
||
additional options to use for the child process.
|
||
|
||
@since 2.9.2
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
struct wxExecuteEnv
|
||
{
|
||
/**
|
||
The initial working directory for the new process.
|
||
|
||
If this field is empty, the current working directory of this process
|
||
is used.
|
||
*/
|
||
wxString cwd;
|
||
|
||
/**
|
||
The environment variable map.
|
||
|
||
If the map is empty, the environment variables of the current process
|
||
are also used for the child one, otherwise only the variables defined
|
||
in this map are used.
|
||
*/
|
||
wxEnvVariableHashMap env;
|
||
};
|
||
|
||
/**
|
||
Bit flags that can be used with wxExecute().
|
||
*/
|
||
enum
|
||
{
|
||
/**
|
||
Execute the process asynchronously.
|
||
|
||
Notice that, due to its value, this is the default.
|
||
*/
|
||
wxEXEC_ASYNC = 0,
|
||
|
||
/**
|
||
Execute the process synchronously.
|
||
*/
|
||
wxEXEC_SYNC = 1,
|
||
|
||
/**
|
||
Always show the child process console under MSW.
|
||
|
||
The child console is hidden by default if the child IO is redirected,
|
||
this flag allows to change this and show it nevertheless.
|
||
|
||
This flag is ignored under the other platforms.
|
||
*/
|
||
wxEXEC_SHOW_CONSOLE = 2,
|
||
|
||
/**
|
||
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. It corresponds to the
|
||
native @c 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_MAKE_GROUP_LEADER = 4,
|
||
|
||
/**
|
||
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_NODISABLE = 8,
|
||
|
||
/**
|
||
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_NOEVENTS = 16,
|
||
|
||
/**
|
||
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.
|
||
|
||
@since 2.9.3
|
||
*/
|
||
wxEXEC_HIDE_CONSOLE = 32,
|
||
|
||
/**
|
||
Convenient synonym for flags given system()-like behaviour.
|
||
*/
|
||
wxEXEC_BLOCK = wxEXEC_SYNC | wxEXEC_NOEVENTS
|
||
};
|
||
/**
|
||
Executes another program in Unix or Windows.
|
||
|
||
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.
|
||
|
||
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 @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().
|
||
|
||
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 @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). Under MSW, this flag can be used with console processes only and
|
||
corresponds to the native @c CREATE_NEW_PROCESS_GROUP flag.
|
||
|
||
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.
|
||
|
||
@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, i.e. "emacs file.txt".
|
||
@param flags
|
||
Must 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.
|
||
@param callback
|
||
An optional pointer to wxProcess.
|
||
@param env
|
||
An 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 wxShell(), wxProcess, @ref page_samples_exec,
|
||
wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
|
||
|
||
@header{wx/utils.h}
|
||
|
||
@beginWxPerlOnly
|
||
In wxPerl this function is called @c Wx::ExecuteCommand.
|
||
@endWxPerlOnly
|
||
*/
|
||
long wxExecute(const wxString& command, int flags = wxEXEC_ASYNC,
|
||
wxProcess* callback = NULL,
|
||
const wxExecuteEnv* env = NULL);
|
||
//@}
|
||
|
||
/** @addtogroup 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
|
||
terminated with a @NULL pointer.
|
||
@param flags
|
||
Same as for wxExecute(const wxString&,int,wxProcess*) overload.
|
||
@param callback
|
||
An optional pointer to wxProcess.
|
||
@param env
|
||
An 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 wxShell(), wxProcess, @ref page_samples_exec,
|
||
wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
|
||
|
||
@header{wx/utils.h}
|
||
|
||
@beginWxPerlOnly
|
||
In wxPerl this function is called @c Wx::ExecuteArgs.
|
||
@endWxPerlOnly
|
||
*/
|
||
long wxExecute(const char* const* argv, int flags = wxEXEC_ASYNC,
|
||
wxProcess* callback = NULL,
|
||
const wxExecuteEnv *env = NULL);
|
||
long wxExecute(const wchar_t* const* argv, int flags = wxEXEC_ASYNC,
|
||
wxProcess* callback = NULL,
|
||
const wxExecuteEnv *env = NULL);
|
||
//@}
|
||
|
||
/** @addtogroup group_funcmacro_procctrl */
|
||
//@{
|
||
|
||
/**
|
||
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 output
|
||
The string array where the stdout of the executed process is saved.
|
||
@param flags
|
||
Combination of flags to which ::wxEXEC_SYNC is always implicitly added.
|
||
@param env
|
||
An 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 wxShell(), wxProcess, @ref page_samples_exec,
|
||
wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
|
||
|
||
@header{wx/utils.h}
|
||
|
||
@beginWxPerlOnly
|
||
This function is called @c Wx::ExecuteStdout: it only takes the
|
||
@a command argument, and returns a 2-element list (@c status, @c output),
|
||
where @c output in an array reference.
|
||
@endWxPerlOnly
|
||
*/
|
||
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 adds the possibility to additionally capture the messages from
|
||
standard error output in the @a errors array. As with the above overload
|
||
capturing standard output only, execution is always synchronous.
|
||
|
||
@param command
|
||
The command to execute and any parameters to pass to it as a single
|
||
string.
|
||
@param output
|
||
The string array where the stdout of the executed process is saved.
|
||
@param errors
|
||
The string array where the stderr of the executed process is saved.
|
||
@param flags
|
||
Combination of flags to which ::wxEXEC_SYNC is always implicitly added.
|
||
@param env
|
||
An 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 wxShell(), wxProcess, @ref page_samples_exec,
|
||
wxLaunchDefaultApplication(), wxLaunchDefaultBrowser()
|
||
|
||
@header{wx/utils.h}
|
||
|
||
@beginWxPerlOnly
|
||
This function is called @c Wx::ExecuteStdoutStderr: 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, wxArrayString& output,
|
||
wxArrayString& errors, int flags = 0,
|
||
const wxExecuteEnv *env = NULL);
|
||
|
||
/**
|
||
Returns the number uniquely identifying the current process in the system.
|
||
If an error occurs, 0 is returned.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
unsigned long wxGetProcessId();
|
||
|
||
/**
|
||
Equivalent to the Unix kill function: send the given signal @a sig to the
|
||
process with PID @a pid.
|
||
|
||
The valid signal values are:
|
||
|
||
@code
|
||
enum wxSignal
|
||
{
|
||
wxSIGNONE = 0, // 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
|
||
};
|
||
@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 wxSIGTERM under Windows. Moreover, under Windows, @c 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 @c 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 @a rc parameter is not @NULL,
|
||
it will be filled with a value from 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
|
||
};
|
||
@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().
|
||
|
||
@see wxProcess::Kill(), wxProcess::Exists(), @ref page_samples_exec
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
int wxKill(long pid, wxSignal sig = wxSIGTERM,
|
||
wxKillError* rc = NULL, int flags = wxKILL_NOCHILDREN);
|
||
|
||
/**
|
||
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}
|
||
*/
|
||
bool wxShell(const wxString& command = wxEmptyString);
|
||
|
||
/**
|
||
This function shuts down or reboots the computer depending on the value of
|
||
the @a flags.
|
||
|
||
@note Note that performing the shutdown requires the corresponding access
|
||
rights (superuser under Unix, SE_SHUTDOWN privilege under Windows)
|
||
and that this function is only implemented under Unix and MSW.
|
||
|
||
@param flags
|
||
One of @c wxSHUTDOWN_POWEROFF, @c wxSHUTDOWN_REBOOT or
|
||
@c wxSHUTDOWN_LOGOFF (currently implemented only for MSW) possibly
|
||
combined with @c 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.
|
||
|
||
@return @true on success, @false if an error occurred.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
bool wxShutdown(int flags = wxSHUTDOWN_POWEROFF);
|
||
|
||
//@}
|
||
|
||
|
||
|
||
/** @addtogroup 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.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
void wxSleep(int secs);
|
||
|
||
/**
|
||
@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.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
void wxUsleep(unsigned long milliseconds);
|
||
|
||
//@}
|
||
|
||
|
||
/** @addtogroup group_funcmacro_misc */
|
||
//@{
|
||
/**
|
||
Convert decimal integer to 2-character hexadecimal string.
|
||
|
||
@param dec
|
||
A number to be converted.
|
||
@param buf
|
||
A pointer to the buffer that receives hexadecimal string (not prefixed
|
||
by @c 0x). This buffer should be large enough to hold at least
|
||
3 characters: 2 hexadecimal digits and the terminating null character.
|
||
|
||
@remarks
|
||
Returned string is composed of uppercase hexdecimal characters.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
void wxDecToHex(unsigned char dec, wxChar *buf);
|
||
|
||
/**
|
||
Convert decimal integer to 2-character hexadecimal string.
|
||
|
||
@param dec
|
||
A number to be converted.
|
||
@return
|
||
String containing hexadecimal string, not prefixed by @c 0x,
|
||
composed of uppercase characters.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
wxString wxDecToHex(unsigned char dec);
|
||
|
||
/**
|
||
Returns 2 characters of hexadecimal representation of a given number.
|
||
|
||
@param dec
|
||
A number to be converted.
|
||
@param ch1
|
||
Pointer to the variable that receives 1st hexadecimal character.
|
||
It must not be @NULL.
|
||
@param ch2
|
||
Pointer to the variable that receives 2nd hexadecimal character.
|
||
It must not be @NULL.
|
||
|
||
@remarks
|
||
Returned characters are uppercase.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
void wxDecToHex(unsigned char dec, char* ch1, char* ch2);
|
||
|
||
/**
|
||
Convert 2-character hexadecimal string to decimal integer.
|
||
|
||
@param buf
|
||
String containing uppercase hexadecimal characters, not prefixed
|
||
by @c 0x. Its length must be at least 2 characters. If it is longer
|
||
than 2 characters, only first two will be converted to the number.
|
||
|
||
@return
|
||
An integer number between 0 and 255 that is equivalent to the number
|
||
in @a buf, or @c -1 if @a buf is not a hexadecimal string.
|
||
|
||
@header{wx/utils.h}
|
||
*/
|
||
int wxHexToDec(const wxString& buf);
|
||
|
||
/**
|
||
@overload
|
||
*/
|
||
int wxHexToDec(const char* buf);
|
||
//@}
|