// Name: utils.h
// Purpose: interface of various utility classes and functions
// Author: wxWidgets team
-// RCS-ID: $Id$
// 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
/**
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);
@header{wx/utils.h}
*/
-void wxBeginBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR);
+void wxBeginBusyCursor(const wxCursor* cursor = wxHOURGLASS_CURSOR);
/**
Changes the cursor back to the original cursor, for all windows in the
@note This function is categorized as a GUI one and so is not thread-safe.
@header{wx/utils.h}
+
+ @library{wxcore}
*/
void wxBell();
@since 2.9.0
+ @see wxGetLibraryVersionInfo()
+
@header{wx/utils.h}
*/
-void wxInfoMessageBox(wxWindow parent = NULL);
+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();
//@}
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);
@header{wx/utils.h}
*/
-long wxNewId();
+int wxNewId();
/**
Ensures that Ids subsequently generated by wxNewId() do not clash with the
@header{wx/utils.h}
*/
-void wxRegisterId(long id);
+void wxRegisterId(int id);
/**
Opens the @a document in the application associated with the files of this
bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0);
/**
- Loads a user-defined Windows resource as a string. If the resource is
- found, the function creates a new character array and copies the data into
- it. A pointer to this data is returned. If unsuccessful, @NULL is returned.
+ Loads an object from Windows resource file.
- The resource must be defined in the @c .rc file using the following syntax:
+ 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
- myResource TEXT file.ext
+ 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
- Where @c file.ext is a file that the resource compiler can find.
+ @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}
*/
-wxString wxLoadUserResource(const wxString& resourceName,
- const wxString& resourceType = "TEXT");
+char* wxLoadUserResource(const wxString& resourceName,
+ const wxChar* resourceType = "TEXT",
+ int* pLen = NULL,
+ WXHINSTANCE module = 0);
/**
@deprecated Replaced by wxWindow::Close(). See the
@header{wx/utils.h}
*/
-extern "C"
-{
-typedef int (wxCMPFUNC_CONV *CMPFUNCDATA)(const void* pItem1, const void* pItem2, const void* user_data);
-}
+typedef int (*wxSortCallback)(const void* pItem1, const void* pItem2, const void* user_data);
/**
- Function for performing a qsort operation including a user data
- parameter.
+ 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 *const pbase, size_t total_elems,
- size_t size, CMPFUNCDATA cmp, const void* user_data);
+void wxQsort(void* pbase, size_t total_elems,
+ size_t size, wxSortCallback cmp, const void* user_data);
/**
*/
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.
'uname -r' command); e.g. "2" and "6" if the machine is using kernel 2.6.19.
For Mac OS X systems (@c wxOS_MAC) the major and minor version integers are the
- natural version numbers associated with the OS; e.g. "10" and and "6" if the machine
+ 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 (@c wxOS_WINDOWS) the major and minor version integers will
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 and is only supported
+ under NT family (i.e. not under Windows 9x). 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.
+ */
+ 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.
wxProcess::OnTerminate() will be called when the process finishes.
Specifying this parameter also allows you to redirect the standard input
and/or output of the process being launched by calling
- wxProcess::Redirect(). If the child process IO is redirected, under Windows
- the process window is not shown by default (this avoids having to flush an
- unnecessary console for the processes which don't create any windows
- anyhow) but a @c wxEXEC_NOHIDE flag can be used to prevent this from
- happening, i.e. with this flag the child process window will be shown
- normally.
+ 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).
+ 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
string, i.e. "emacs file.txt".
@param flags
Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
- wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
- wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
- their combination, in wxEXEC_SYNC case.
+ 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
additional ones are the command parameters and the array must be
terminated with a @NULL pointer.
@param flags
- Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
- wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
- wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
- their combination, in wxEXEC_SYNC case.
+ Same as for wxExecute(const wxString&,int,wxProcess*) overload.
@param callback
An optional pointer to wxProcess.
@param env
@param output
The string array where the stdout of the executed process is saved.
@param flags
- May include wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
- wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
- their combination. wxEXEC_SYNC is always implicitly added to the 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
@param errors
The string array where the stderr of the executed process is saved.
@param flags
- May include wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
- wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
- their combination. wxEXEC_SYNC is always implicitly added to the 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
@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.
+ @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:
@header{wx/utils.h}
*/
-int wxKill(long pid, int sig = wxSIGTERM,
- wxKillError rc = NULL, int flags = 0);
+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
@header{wx/utils.h}
*/
-bool wxShell(const wxString& command = NULL);
+bool wxShell(const wxString& command = wxEmptyString);
/**
This function shuts down or reboots the computer depending on the value of
projects / wxWidgets.git / blobdiff