/////////////////////////////////////////////////////////////////////////////
// Name: utils.h
-// Purpose: documentation for wxWindowDisabler class
+// Purpose: interface of various utility classes and functions
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
/**
@class wxWindowDisabler
@wxheader{utils.h}
-
- 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.
- This comes in handy when you want to indicate to the user that the application
+
+ 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.
+
+ This is useful when you want to indicate to the user that the application
is currently busy and cannot respond to user input.
-
+
@library{wxcore}
- @category{FIXME}
-
- @seealso
- wxBusyCursor
+ @category{misc}
+
+ @see wxBusyCursor
*/
-class wxWindowDisabler
+class wxWindowDisabler
{
public:
/**
- Disables all top level windows of the applications with the exception of
- @e winToSkip if it is not @NULL.
+ 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(wxWindow * winToSkip = @NULL);
+ wxWindowDisabler(bool disable = true);
/**
- Reenables back the windows disabled by the constructor.
+ Disables all top level windows of the applications with the exception
+ of @a winToSkip if it is not @NULL.
+ */
+ wxWindowDisabler(wxWindow* winToSkip);
+
+ /**
+ Reenables the windows disabled by the constructor.
*/
~wxWindowDisabler();
};
+
/**
@class wxBusyCursor
@wxheader{utils.h}
-
- 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.
-
+
+ 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++)
+
+ for (int i = 0; i < 100000; i++)
DoACalculation();
@endcode
-
- It works by calling wxBeginBusyCursor in the constructor,
- and wxEndBusyCursor in the destructor.
-
+
+ It works by calling wxBeginBusyCursor() in the constructor, and
+ wxEndBusyCursor() in the destructor.
+
@library{wxcore}
- @category{FIXME}
-
- @seealso
- wxBeginBusyCursor, wxEndBusyCursor, wxWindowDisabler
+ @category{misc}
+
+ @see wxBeginBusyCursor(), wxEndBusyCursor(), wxWindowDisabler
*/
-class wxBusyCursor
+class wxBusyCursor
{
public:
/**
- Constructs a busy cursor object, calling wxBeginBusyCursor.
+ Constructs a busy cursor object, calling wxBeginBusyCursor().
*/
wxBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR);
/**
- Destroys the busy cursor object, calling wxEndBusyCursor.
+ Destroys the busy cursor object, calling wxEndBusyCursor().
*/
~wxBusyCursor();
};
+
+/**
+ @class wxMouseState
+ @wxheader{utils.h}
+
+ Represents the mouse state.
+
+ The methods of this class generally mirror the corresponding methods of
+ wxMouseEvent.
+
+ This class is implemented entirely in @<wx/utils.h@>, meaning no extra
+ library needs to be linked to use this class.
+
+ @category{misc}
+
+ @see wxGetMouseState()
+ */
+class wxMouseState
+{
+public:
+ /**
+ Default constructor.
+ */
+ wxMouseState();
+
+ /**
+ Returns X coordinate of the physical mouse event position.
+ */
+ wxCoord GetX() const;
+ /**
+ Returns Y coordinate of the physical mouse event position.
+ */
+ wxCoord GetY() const;
+ /**
+ Returns the physical mouse position.
+ */
+ wxPoint GetPosition() const;
+
+ /**
+ Returns @true if the left mouse button changed to down.
+ */
+ bool LeftDown() const;
+ /**
+ Returns @true if the middle mouse button changed to down.
+ */
+ bool MiddleDown() const;
+ /**
+ Returns @true if the right mouse button changed to down.
+ */
+ bool RightDown() const;
+ /**
+ Returns @true if the first extra button mouse button changed to down.
+ */
+ bool Aux1Down() const;
+ /**
+ Returns @true if the second extra button mouse button changed to down.
+ */
+ bool Aux2Down() const;
+
+ /**
+ Returns @true if the control key is down.
+ */
+ bool ControlDown() const;
+ /**
+ Returns @true if the shift key is down.
+ */
+ bool ShiftDown() const;
+ /**
+ Returns @true if the alt key is down.
+ */
+ bool AltDown() const;
+ /**
+ Returns @true if the meta key is down.
+ */
+ bool MetaDown() const;
+ /**
+ Same as MetaDown() under Mac systems, ControlDown() for the others.
+ */
+ bool CmdDown() const;
+};
+
+
// ============================================================================
// Global functions/macros
// ============================================================================
+
+/** @ingroup group_funcmacro_dialog */
+//@{
+
/**
- 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).
+ 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}
*/
-wxPowerType wxGetPowerType();
+void wxBeginBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR);
-//@{
/**
- 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.
-
- The first variant of this function returns the login name if successful or an
- empty string otherwise. The second (deprecated) function returns @true
- if successful, @false otherwise.
-
- @sa wxGetUserName
+ Changes the cursor back to the original cursor, for all windows in the
+ application. Use with wxBeginBusyCursor().
+
+ @see wxIsBusy(), wxBusyCursor
+
+ @header{wx/utils.h}
*/
-wxString wxGetUserId();
- bool wxGetUserId(char * buf, int sz);
+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}
+*/
+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
+
+ @header{wx/utils.h}
+*/
+void wxInfoMessageBox(wxWindow parent = NULL);
+
//@}
+
+
+/** @ingroup group_funcmacro_env */
+//@{
+
/**
- @b NB: This function is now obsolete, please use
- wxLogFatalError instead.
-
- Displays @e msg and exits. This writes to standard error under Unix,
- and pops up a message box under Windows. Used for fatal internal
- wxWidgets errors. See also wxError.
+ 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}
*/
-void wxFatalError(const wxString& msg,
- const wxString& title = "wxWidgets Fatal Error");
+wxChar* wxGetenv(const wxString& var);
/**
- 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).
+ Returns the current value of the environment variable @c var in @c value.
+ @c 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}
*/
-wxBatteryState wxGetBatteryState();
+bool wxGetEnv(const wxString& var, wxString* value);
/**
- @b NB: This function is obsolete, please use
- wxWindow::FindWindowByName instead.
-
- Find a window by its name (as given in a window constructor or @b Create
- function call).
- If @e 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, @b wxFindWindowByLabel is called.
+ Sets the value of the environment variable @c var (adding it if necessary)
+ to @c value.
+
+ Returns @true on success.
+
+ @see wxUnsetEnv()
+
+ @header{wx/utils.h}
*/
-wxWindow * wxFindWindowByName(const wxString& name,
- wxWindow * parent=@NULL);
+bool wxSetEnv(const wxString& var, const wxString& value);
/**
- Changes the cursor back to the original cursor, for all windows in the
- application.
- Use with wxBeginBusyCursor.
-
- See also wxIsBusy, wxBusyCursor.
+ Removes the variable @c var from the environment. wxGetEnv() will return
+ @NULL after the call to this function.
+
+ Returns @true on success.
+
+ @header{wx/utils.h}
*/
-void wxEndBusyCursor();
+bool wxUnsetEnv(const wxString& var);
+
+//@}
+
+
+
+/** @ingroup group_funcmacro_misc */
+//@{
/**
- This function is deprecated as the 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.
+ 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}
*/
-long wxNewId();
+wxBatteryState wxGetBatteryState();
/**
- Ensures that ids subsequently generated by @b NewId do not clash with
- the given @b id.
+ 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}
*/
-void wxRegisterId(long id);
+wxPowerType wxGetPowerType();
/**
- @b NB: This function is now obsolete, replaced by Log
- functions and wxLogDebug in particular.
-
- Display a debugging message; under Windows, this will appear on the
- debugger command window, and under Unix, it will be written to standard
- error.
-
- The syntax is identical to @b printf: pass a format string and a
- variable list of arguments.
-
- @b Tip: under Windows, if your application crashes before the
- message appears in the debugging window, put a wxYield call after
- each wxDebugMsg call. wxDebugMsg seems to be broken under WIN32s
- (at least for Watcom C++): preformat your messages and use OutputDebugString
- instead.
+ Under X only, returns the current display name.
+
+ @see wxSetDisplayName()
+
+ @header{wx/utils.h}
*/
-void wxDebugMsg(const wxString& fmt, ... );
+wxString wxGetDisplayName();
/**
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.
-
+
+ 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.
+
+ @header{wx/utils.h}
*/
bool wxGetKeyState(wxKeyCode key);
/**
- Returns the string containing the description of the current platform in a
- user-readable form. For example, this function may return strings like
- @c Windows NT Version 4.0 or @c Linux 2.2.2 i386.
-
- @sa ::wxGetOsVersion
+ Returns the mouse position in screen coordinates.
+
+ @header{wx/utils.h}
*/
-wxString wxGetOsDescription();
+wxPoint wxGetMousePosition();
/**
- Return the (current) user's home directory.
-
- @sa wxGetUserHome, wxStandardPaths
+ 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}
*/
-wxString wxGetHomeDir();
+wxMouseState wxGetMouseState();
/**
- Sleeps for the specified number of milliseconds. Notice that usage of this
- function is encouraged instead of calling usleep(3) directly because the
- standard usleep() function is not MT safe.
+ This function enables or disables all top level windows. It is used by
+ wxSafeYield().
+
+ @header{wx/utils.h}
*/
-void wxMilliSleep(unsigned long milliseconds);
+void wxEnableTopLevelWindows(bool enable = true);
/**
- Sleeps for the specified number of microseconds. The microsecond resolution may
- not, in fact, be available on all platforms (currently only Unix platforms with
- nanosleep(2) may provide it) in which case this is the same as
- wxMilliSleep(@e microseconds/1000).
+ Find the deepest window at the given mouse position in screen coordinates,
+ returning the window if found, or @NULL if not.
+
+ @header{wx/utils.h}
*/
-void wxMicroSleep(unsigned long microseconds);
+wxWindow* wxFindWindowAtPoint(const wxPoint& pt);
/**
- 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.
-
- This function is new since wxWidgets version 2.9.0
+ @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}
*/
-void wxInfoMessageBox(wxWindow ( parent = @NULL);
+wxWindow* wxFindWindowByLabel(const wxString& label,
+ wxWindow* parent = NULL);
/**
- Find a menu item identifier associated with the given frame's menu bar.
+ @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}
*/
-int wxFindMenuItemId(wxFrame * frame, const wxString& menuString,
- const wxString& itemString);
+wxWindow* wxFindWindowByName(const wxString& name, wxWindow* parent = NULL);
/**
- This function enables or disables all top level windows. It is used by
- ::wxSafeYield.
+ Find a menu item identifier associated with the given frame's menu bar.
+
+ @header{wx/utils.h}
*/
-void wxEnableTopLevelWindows(bool enable = @true);
+int wxFindMenuItemId(wxFrame* frame, const wxString& menuString,
+ const wxString& itemString);
/**
- Strips any menu codes from @e 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 @e 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.
+ @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}
*/
-wxString wxStripMenuCodes(const wxString& str,
- int flags = wxStrip_All);
+long wxNewId();
/**
- @b NB: This function is now obsolete, please use wxLogError
- instead.
-
- Displays @e msg and continues. This writes to standard error under
- Unix, and pops up a message box under Windows. Used for internal
- wxWidgets errors. See also wxFatalError.
+ Ensures that Ids subsequently generated by wxNewId() do not clash with the
+ given @a id.
+
+ @header{wx/utils.h}
*/
-void wxError(const wxString& msg,
- const wxString& title = "wxWidgets Internal Error");
+void wxRegisterId(long id);
/**
- Open the @e url in user's default browser. If @e flags parameter contains
- @c wxBROWSER_NEW_WINDOW flag, a new window is opened for the URL
- (currently this is only supported under Windows). The @e url may also be a
- local file path (with or without @c file:// prefix), if it doesn't
- correspond to an existing file and the URL has no scheme @c http:// is
+ 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). The @a url may also be a
+ local file path (with or without the "file://" prefix), if it doesn't
+ correspond to an existing file and the URL has no scheme "http://" is
prepended to it by default.
-
+
Returns @true if the application was successfully launched.
-
- Note that 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).
+
+ @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).
+
+ @header{wx/utils.h}
*/
bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0);
/**
- Executes a command in an interactive shell window. If no command is
- specified, then just the shell is spawned.
-
- See also wxExecute, @ref overview_sampleexec "Exec sample".
+ 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.
+
+ The resource must be defined in the @c .rc file using the following syntax:
+
+ @code
+ myResource TEXT file.ext
+ @endcode
+
+ Where @c file.ext is a file that the resource compiler can find.
+
+ This function is available under Windows only.
+
+ @header{wx/utils.h}
*/
-bool wxShell(const wxString& command = @NULL);
+wxString wxLoadUserResource(const wxString& resourceName,
+ const wxString& resourceType = "TEXT");
/**
- Gets the version and the operating system ID for currently running OS.
- See wxPlatformInfo for more details about wxOperatingSystemId.
-
- @sa ::wxGetOsDescription, wxPlatformInfo
+ @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}
*/
-wxOperatingSystemId wxGetOsVersion(int * major = @NULL,
- int * minor = @NULL);
+void wxPostDelete(wxObject* object);
/**
- Returns the FQDN (fully qualified domain host name) or an empty string on
- error.
-
- @sa wxGetHostName
+ 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}
*/
-wxString wxGetFullHostName();
+void wxSetDisplayName(const wxString& displayName);
/**
- 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.
+ 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}
*/
-void wxBeginBusyCursor(wxCursor * cursor = wxHOURGLASS_CURSOR);
+wxString wxStripMenuCodes(const wxString& str, int flags = wxStrip_All);
+
+//@}
+
+
+
+/** @ingroup group_funcmacro_networkuseros */
+//@{
/**
- 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.
-
- Now obsolete: use wxWindow::Close instead.
+ Copies the user's email address into the supplied buffer, by concatenating
+ the values returned by wxGetFullHostName() and wxGetUserId().
+
+ @returns @true if successful, @false otherwise.
+
+ @header{wx/utils.h}
*/
-void wxPostDelete(wxObject * object);
+wxString wxGetEmailAddress();
/**
- @b NB: This function is obsolete, please use
- wxWindow::FindWindowByLabel instead.
-
- Find a window by its label. Depending on the type of window, the label may be a
- window title
- or panel item label. If @e 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.
+ @deprecated Use wxGetEmailAddress() instead.
+
+ @param buf Buffer to store the email address in.
+ @param sz Size of the buffer.
+
+ @returns @true if successful, @false otherwise.
+
+ @header{wx/utils.h}
*/
-wxWindow * wxFindWindowByLabel(const wxString& label,
- wxWindow * parent=@NULL);
+bool wxGetEmailAddress(char* buf, int sz);
/**
- This function is similar to wxYield, except that it disables the user input to
- all program windows before calling wxYield and re-enables it again
- afterwards. If @e win is not @NULL, this window will remain enabled,
- allowing the implementation of some limited user interaction.
-
- Returns the result of the call to ::wxYield.
+ 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}
*/
-bool wxSafeYield(wxWindow* win = @NULL, bool onlyIfNeeded = @false);
+wxMemorySize wxGetFreeMemory();
/**
- Returns the mouse position in screen coordinates.
+ Return the (current) user's home directory.
+
+ @see wxGetUserHome(), wxStandardPaths
+
+ @header{wx/utils.h}
*/
-wxPoint wxGetMousePosition();
+wxString wxGetHomeDir();
/**
- 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.
-
- The resource must be defined in the @c .rc file using the following syntax:
- @code
- myResource TEXT file.ext
- @endcode
-
- where @c file.ext is a file that the resource compiler can find.
-
- This function is available under Windows only.
+ Copies the current host machine's name into the supplied buffer. Please
+ note that the returned name is @e not fully qualified, i.e. it does not
+ include the domain name.
+
+ Under Windows or NT, this function first looks in the environment variable
+ SYSTEM_NAME; if this is not found, the entry @b HostName in the wxWidgets
+ section of the WIN.INI file is tried.
+
+ @returns The hostname if successful or an empty string otherwise.
+
+ @see wxGetFullHostName()
+
+ @header{wx/utils.h}
*/
-wxString wxLoadUserResource(const wxString& resourceName,
- const wxString& resourceType="TEXT");
+wxString wxGetHostName();
/**
- Returns the amount of free memory in bytes under environments which
- support it, and -1 if not supported or failed to perform measurement.
+ @deprecated Use wxGetHostName() instead.
+
+ @param buf Buffer to store the host name in.
+ @param sz Size of the buffer.
+
+ @returns @true if successful, @false otherwise.
+
+ @header{wx/utils.h}
*/
-wxMemorySize wxGetFreeMemory();
+bool wxGetHostName(char* buf, int sz);
/**
- 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.
+ Returns the FQDN (fully qualified domain host name) or an empty string on
+ error.
+
+ @see wxGetHostName()
+
+ @header{wx/utils.h}
*/
-wxChar * wxGetEnv(const wxString& var);
+wxString wxGetFullHostName();
-//@{
/**
- Copies the current host machine's name into the supplied buffer. Please note
- that the returned name is @e not fully qualified, i.e. it does not include
- the domain name.
-
- Under Windows or NT, this function first looks in the environment
- variable SYSTEM_NAME; if this is not found, the entry @b HostName
- in the @b wxWidgets section of the WIN.INI file is tried.
-
- The first variant of this function returns the hostname if successful or an
- empty string otherwise. The second (deprecated) function returns @true
- if successful, @false otherwise.
-
- @sa 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 wxGetHostName();
- bool wxGetHostName(char * buf, int sz);
-//@}
+wxString wxGetUserHome(const wxString& user = "");
/**
- Returns the current value of the environment variable @e var in @e value.
- @e 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.
+ This function returns the "user id" also known as "login name" under Unix
+ (i.e. something like "jsmith"). It uniquely identifies the current user (on
+ this system). Under Windows or NT, this function first looks in the
+ environment variables USER and LOGNAME; if neither of these is found, the
+ entry @b UserId in the @b wxWidgets section of the WIN.INI file is tried.
+
+ @returns The login name if successful or an empty string otherwise.
+
+ @see wxGetUserName()
+
+ @header{wx/utils.h}
*/
-bool wxGetEnv(const wxString& var, wxString * value);
+wxString wxGetUserId();
/**
- Under X only, returns the current display name. See also wxSetDisplayName.
+ @deprecated Use wxGetUserId() instead.
+
+ @param buf Buffer to store the login name in.
+ @param sz Size of the buffer.
+
+ @returns @true if successful, @false otherwise.
+
+ @header{wx/utils.h}
*/
-wxString wxGetDisplayName();
+bool wxGetUserId(char* buf, int sz);
/**
- Ring the system bell.
-
- Note that this function is categorized as a GUI one and so is not thread-safe.
+ This function returns the full user name (something like "Mr. John Smith").
+
+ Under Windows or NT, this function looks for the entry UserName in the
+ wxWidgets section of the WIN.INI file. If PenWindows is running, the entry
+ Current in the section User of the PENWIN.INI file is used.
+
+ @returns The full user name if successful or an empty string otherwise.
+
+ @see wxGetUserId()
+
+ @header{wx/utils.h}
*/
-void wxBell();
+wxString wxGetUserName();
/**
- Returns the home directory for the given user. If the @e 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.
+ @deprecated Use wxGetUserName() instead.
+
+ @param buf Buffer to store the full user name in.
+ @param sz Size of the buffer.
+
+ @returns @true if successful, @false otherwise.
+
+ @header{wx/utils.h}
*/
-wxString wxGetUserHome(const wxString& user = "");
+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 NT Version 4.0" or "Linux 2.2.2 i386".
+
+ @see wxGetOsVersion()
+
+ @header{wx/utils.h}
+*/
+wxString wxGetOsDescription();
+
+/**
+ Gets the version and the operating system ID for currently running OS. See
+ wxPlatformInfo for more details about wxOperatingSystemId.
+
+ @see wxGetOsDescription(), wxPlatformInfo
+
+ @header{wx/utils.h}
+*/
+wxOperatingSystemId wxGetOsVersion(int* major = NULL, int* minor = NULL);
+
+/**
+ 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();
+
+//@}
+
+
+/** @ingroup group_funcmacro_procctrl */
//@{
+
/**
- @b wxPerl note: In wxPerl this function is called @c Wx::ExecuteStdoutStderr
- and it only takes the @c command argument,
- and returns a 3-element list @c ( status, output, errors ), where
- @c output and @c errors are array references.
-
Executes another program in Unix or Windows.
-
- The first form takes a command string, such as @c "emacs file.txt".
-
- The second form takes an array of values: a command, any number of
- arguments, terminated by @NULL.
-
- The semantics of the third and fourth versions is different from the first two
- and is described in more details below.
-
- If @e flags parameter contains @c wxEXEC_ASYNC flag (the default), flow
- of control immediately returns. If it contains @c wxEXEC_SYNC, the current
- application waits until the other program has terminated.
-
+
+ In the overloaded versions of this function, if @a flags parameter contains
+ @c wxEXEC_ASYNC flag (the default), flow of control immediately returns. If
+ it contains @c wxEXEC_SYNC, the current application waits until the other
+ program has terminated.
+
In the case of synchronous execution, the return value is the exit code of
- the process (which terminates by the moment the function returns) and will be
- -1 if the process couldn't be started and typically 0 if the process
- terminated successfully. Also, while waiting for the process to
- terminate, wxExecute will call wxYield. Because of this, by
- default this function disables all application windows to avoid unexpected
- reentrancies which could result from the users interaction with the program
- while the child process is running. If you are sure that it is safe to not
- disable the program windows, you may pass @c wxEXEC_NODISABLE flag to
- prevent this automatic disabling from happening.
-
+ the process (which terminates by the moment the function returns) and will
+ be -1 if the process couldn't be started and typically 0 if the process
+ terminated successfully. Also, while waiting for the process to terminate,
+ wxExecute() will call wxYield(). Because of this, by default this function
+ disables all application windows to avoid unexpected reentrancies which
+ could result from the users interaction with the program while the child
+ process is running. If you are sure that it is safe to not disable the
+ program windows, you may pass @c wxEXEC_NODISABLE flag to prevent this
+ automatic disabling from happening.
+
For asynchronous execution, however, the return value is the process id and
zero value indicates that the command could not be executed. As an added
complication, the return value of -1 in this case indicates that we didn't
- launch a new process, but connected to the running one (this can only happen in
- case of using DDE under Windows for command execution). In particular, in this,
- and only this, case the calling code will not get the notification about
+ launch a new process, but connected to the running one (this can only
+ happen when using DDE under Windows for command execution). In particular,
+ in this case only, the calling code will not get the notification about
process termination.
-
- If callback isn't @NULL and if execution is asynchronous,
- wxProcess::OnTerminate will be called when
- the process finishes. Specifying this parameter also allows you to redirect the
- standard input and/or output of the process being launched by calling
- wxProcess::Redirect. If the child process IO is redirected,
- under Windows the process window is not shown by default (this avoids having to
- flush an unnecessary console for the processes which don't create any windows
+
+ If @a callback isn't @NULL and if execution is asynchronous,
+ wxProcess::OnTerminate() will be called when the process finishes.
+ Specifying this parameter also allows you to redirect the standard input
+ and/or output of the process being launched by calling
+ wxProcess::Redirect(). If the child process IO is redirected, under Windows
+ the process window is not shown by default (this avoids having to flush an
+ unnecessary console for the processes which don't create any windows
anyhow) but a @c wxEXEC_NOHIDE flag can be used to prevent this from
- happening, i.e. with this flag the child process window will be shown normally.
-
- Under Unix the flag @c wxEXEC_MAKE_GROUP_LEADER may be used to ensure
- that the new process is a group leader (this will create a new session if
- needed). Calling wxKill passing wxKILL_CHILDREN will
- kill this process as well as all of its children (except those which have
- started their own session).
-
+ happening, i.e. with this flag the child process window will be shown
+ normally.
+
+ Under Unix the flag @c wxEXEC_MAKE_GROUP_LEADER may be used to ensure that
+ the new process is a group leader (this will create a new session if
+ needed). Calling wxKill() passing wxKILL_CHILDREN will kill this process as
+ well as all of its children (except those which have started their own
+ session).
+
The @c wxEXEC_NOEVENTS flag prevents processing of any events from taking
place while the child process is running. It should be only used for very
short-lived processes as otherwise the application windows risk becoming
- unresponsive from the users point of view. As this flag only makes sense with
- @c wxEXEC_SYNC, @c wxEXEC_BLOCK equal to the sum of both of these flags
- is provided as a convenience.
-
- Finally, you may use the third overloaded version of this function to execute
- a process (always synchronously, the contents of @e flags is or'd with
- @c wxEXEC_SYNC) and capture its output in the array @e output. The
- fourth version adds the possibility to additionally capture the messages from
- standard error output in the @e errors array.
-
- @b NB: Currently wxExecute() can only be used from the main thread, calling
- this function from another thread will result in an assert failure in debug
- build and won't work.
-
- @param command
- The command to execute and any parameters to pass to it as a
- single string.
-
- @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
- Combination of bit masks wxEXEC_ASYNC,
- wxEXEC_SYNC and wxEXEC_NOHIDE
-
- @param callback
- An optional pointer to wxProcess
-
- @sa wxShell, wxProcess, @ref overview_sampleexec "Exec sample".
-*/
-long wxExecute(const wxString& command, int sync = wxEXEC_ASYNC,
- wxProcess * callback = @NULL);
- wxPerl note: long wxExecute(char ** argv,
- int flags = wxEXEC_ASYNC,
- wxProcess * callback = @NULL);
- wxPerl note: long wxExecute(const wxString& command,
- wxArrayString& output,
- int flags = 0);
- wxPerl note: long wxExecute(const wxString& command,
- wxArrayString& output,
- wxArrayString& errors,
- int flags = 0);
+ 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_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
+ wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
+ their combination, in wxEXEC_SYNC case.
+ @param callback
+ An optional pointer to wxProcess.
+
+ @see wxShell(), wxProcess, @ref page_samples_exec
+
+ @header{wx/utils.h}
+
+ @beginWxPerlOnly
+ This function is called @c Wx::ExecuteStdoutStderr and it only takes the
+ @a command argument, and returns a 3-element list (@c status, @c output,
+ @c errors), where @c output and @c errors are array references.
+ @endWxPerlOnly
+*/
+long wxExecute(const wxString& command, int flags = wxEXEC_ASYNC,
+ wxProcess* callback = NULL);
+
//@}
+/** @ingroup group_funcmacro_procctrl */
+//@{
/**
- Returns a string representing the current date and time.
+ This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
+ please see its documentation for general information.
+
+ This version 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
+ Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
+ wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
+ wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
+ their combination, in wxEXEC_SYNC case.
+ @param callback
+ An optional pointer to wxProcess.
+
+ @header{wx/utils.h}
+*/
+long wxExecute(char** argv, int flags = wxEXEC_ASYNC,
+ wxProcess* callback = NULL);
+long wxExecute(wchar_t** argv, int flags = wxEXEC_ASYNC,
+ wxProcess* callback = NULL);
+//@}
+
+/** @ingroup group_funcmacro_procctrl */
+//@{
+
+/**
+ This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
+ please see its documentation for general information.
+
+ This version can be used to execute a process (always synchronously, the
+ contents of @a flags is or'd with @c wxEXEC_SYNC) and capture its output in
+ the array @e output.
+
+ @param command
+ The command to execute and any parameters to pass to it as a single
+ string.
+ @param flags
+ Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
+ wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
+ wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
+ their combination, in wxEXEC_SYNC case.
+
+ @header{wx/utils.h}
*/
-wxString wxNow();
+long wxExecute(const wxString& command, wxArrayString& output,
+ int flags = 0);
/**
- Returns @true if the operating system the program is running under is 64 bit.
- The check is performed at run-time and may differ from the value available at
- compile-time (at compile-time you can just check if @c sizeof(void*)==8)
- since the program could be running in emulation mode or in a mixed 32/64 bit
- system
- (bi-architecture operating system).
-
- Very important: this function is not 100% reliable on some systems given the
- fact
- that there isn't always a standard way to do a reliable check on the OS
- architecture.
+ This is an overloaded version of wxExecute(const wxString&,int,wxProcess*),
+ please see its documentation for general information.
+
+ This version adds the possibility to additionally capture the messages from
+ standard error output in the @a errors array.
+
+ @param command
+ The command to execute and any parameters to pass to it as a single
+ string.
+ @param flags
+ Must include either wxEXEC_ASYNC or wxEXEC_SYNC and can also include
+ wxEXEC_NOHIDE, wxEXEC_MAKE_GROUP_LEADER (in either case) or
+ wxEXEC_NODISABLE and wxEXEC_NOEVENTS or wxEXEC_BLOCK, which is equal to
+ their combination, in wxEXEC_SYNC case.
+
+ @header{wx/utils.h}
*/
-bool wxIsPlatform64Bit();
+long wxExecute(const wxString& command, wxArrayString& output,
+ wxArrayString& errors, int flags = 0);
/**
Returns the number uniquely identifying the current process in the system.
-
If an error occurs, 0 is returned.
+
+ @header{wx/utils.h}
*/
unsigned long wxGetProcessId();
/**
- Equivalent to the Unix kill function: send the given signal @e sig to the
- process with PID @e pid. The valid signal values are
+ 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
+ wxSIGNONE = 0, // verify if the process exists under Unix
wxSIGHUP,
wxSIGINT,
wxSIGQUIT,
wxSIGABRT,
wxSIGEMT,
wxSIGFPE,
- wxSIGKILL, // forcefully kill, dangerous!
+ wxSIGKILL, // forcefully kill, dangerous!
wxSIGBUS,
wxSIGSEGV,
wxSIGSYS,
wxSIGPIPE,
wxSIGALRM,
- wxSIGTERM // terminate the process gently
+ wxSIGTERM // terminate the process gently
};
@endcode
-
- @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning
- under both Unix and Windows but all the other signals are equivalent to
+
+ @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning under
+ both Unix and Windows but all the other signals are equivalent to
@c wxSIGTERM under Windows.
-
- Returns 0 on success, -1 on failure. If @e rc parameter is not @NULL, it will
- be filled with an element of @c wxKillError enum:
+
+ Returns 0 on success, -1 on failure. If the @a rc parameter is not @NULL,
+ it will be filled with a value of the the @c wxKillError enum:
+
@code
enum wxKillError
{
- wxKILL_OK, // no error
- wxKILL_BAD_SIGNAL, // no such signal
- wxKILL_ACCESS_DENIED, // permission denied
- wxKILL_NO_PROCESS, // no such process
- wxKILL_ERROR // another, unspecified error
+ wxKILL_OK, // no error
+ wxKILL_BAD_SIGNAL, // no such signal
+ wxKILL_ACCESS_DENIED, // permission denied
+ wxKILL_NO_PROCESS, // no such process
+ wxKILL_ERROR // another, unspecified error
};
@endcode
-
- The @e 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.
-
- @sa wxProcess::Kill, wxProcess::Exists, @ref overview_sampleexec "Exec sample"
+
+ 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, int sig = wxSIGTERM, wxKillError rc = @NULL,
- int flags = 0);
+int wxKill(long pid, int sig = wxSIGTERM,
+ wxKillError rc = NULL, int flags = 0);
/**
- 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.
+ 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}
*/
-wxMouseState wxGetMouseState();
+bool wxShell(const wxString& command = NULL);
/**
- Returns @true if between two wxBeginBusyCursor and
- wxEndBusyCursor calls.
-
- See also wxBusyCursor.
+ This function shuts down or reboots the computer depending on the value of
+ the @a flags.
+
+ @note Doing this requires the corresponding access rights (superuser under
+ Unix, SE_SHUTDOWN privilege under Windows NT) and that this function
+ is only implemented under Unix and Win32.
+
+ @param flags
+ Either wxSHUTDOWN_POWEROFF or wxSHUTDOWN_REBOOT
+
+ @returns @true on success, @false if an error occurred.
+
+ @header{wx/utils.h}
*/
-bool wxIsBusy();
+bool wxShutdown(wxShutdownFlags flags);
+
+//@}
+
+
+/** @ingroup group_funcmacro_time */
//@{
+
/**
- 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.
+ 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}
*/
-wxString wxGetEmailAddress();
- bool wxGetEmailAddress(char * buf, int sz);
-//@}
+void wxMicroSleep(unsigned long microseconds);
/**
- Sleeps for the specified number of seconds.
+ 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 wxSleep(int secs);
+void wxMilliSleep(unsigned long milliseconds);
/**
- Sets the value of the environment variable @e var (adding it if necessary)
- to @e value.
-
- Returns @true on success.
-
- @sa wxUnsetEnv
+ Returns a string representing the current date and time.
+
+ @header{wx/utils.h}
*/
-bool wxSetEnv(const wxString& var, const wxString& value);
+wxString wxNow();
/**
- Returns @true if the current platform is little endian (instead of big
- endian).
- The check is performed at run-time.
-
- @sa @ref overview_byteordermacros "Byte order macros"
+ Sleeps for the specified number of seconds.
+
+ @header{wx/utils.h}
*/
-bool wxIsPlatformLittleEndian();
+void wxSleep(int secs);
/**
- 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.
+ @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 wxSetDisplayName(const wxString& displayName);
+void wxUsleep(unsigned long milliseconds);
+
+//@}
projects / wxWidgets.git / blobdiff