Contents Up Previous Next

Miscellaneous functions

::wxDROP_ICON
::wxNewId
::wxRegisterId
::wxBeginBusyCursor
::wxBell
::wxCreateDynamicObject
::wxDDECleanUp
::wxDDEInitialize
::wxDebugMsg
::wxDisplaySize
::wxEnableTopLevelWindows
::wxEntry
::wxEndBusyCursor
::wxError
::wxExecute
::wxExit
::wxFatalError
::wxFindMenuItemId
::wxFindWindowByLabel
::wxFindWindowByName
::wxGetActiveWindow
::wxGetDisplayName
::wxGetHomeDir
::wxGetFreeMemory
::wxGetMousePosition
::wxGetOsDescription
::wxGetOsVersion
::wxGetResource
::wxGetUserId
::wxGetUserHome
::wxGetUserName
::wxHandleFatalExceptions
::wxKill
::wxInitAllImageHandlers
::wxIsBusy
::wxLoadUserResource
::wxNow
::wxPostDelete
::wxPostEvent
::wxSafeYield
::wxSetDisplayName
::wxShell
::wxSleep
::wxStripMenuCodes
::wxToLower
::wxToUpper
::wxTrace
::wxTraceLevel
::wxUsleep
::wxWriteResource
::wxYield
::wxWakeUpIdle


::wxDROP_ICON

wxIconOrCursor wxDROP_ICON(const char *name)

This macro creates either a cursor (MSW) or an icon (elsewhere) with the given name. Under MSW, the cursor is loaded from the resource file and the icon is loaded from XPM file under other platforms.

This macro should be used with wxDropSource constructor.

Include files

<wx/dnd.h>


::wxNewId

long wxNewId()

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

Include files

<wx/utils.h>


::wxRegisterId

void wxRegisterId(long id)

Ensures that ids subsequently generated by NewId do not clash with the given id.

Include files

<wx/utils.h>


::wxBeginBusyCursor

void wxBeginBusyCursor(wxCursor *cursor = wxHOURGLASS_CURSOR)

Changes the cursor to the given cursor for all windows in the application. Use wxEndBusyCursor to revert the cursor back to its previous state. These two calls can be nested, and a counter ensures that only the outer calls take effect.

See also wxIsBusy, wxBusyCursor.

Include files

<wx/utils.h>


::wxBell

void wxBell()

Ring the system bell.

Include files

<wx/utils.h>


::wxCreateDynamicObject

wxObject * wxCreateDynamicObject(const wxString& className)

Creates and returns an object of the given class, if the class has been registered with the dynamic class system using DECLARE... and IMPLEMENT... macros.


::wxDDECleanUp

void wxDDECleanUp()

Called when wxWindows exits, to clean up the DDE system. This no longer needs to be called by the application.

See also wxDDEInitialize.

Include files

<wx/dde.h>


::wxDDEInitialize

void wxDDEInitialize()

Initializes the DDE system. May be called multiple times without harm.

This no longer needs to be called by the application: it will be called by wxWindows if necessary.

See also wxDDEServer, wxDDEClient, wxDDEConnection, wxDDECleanUp.

Include files

<wx/dde.h>


::wxDebugMsg

void wxDebugMsg(const wxString& fmt, ...)

This function is deprecated, use wxLogDebug instead!

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 printf: pass a format string and a variable list of arguments.

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.

This function is now obsolete, replaced by Log functions.

Include files

<wx/utils.h>


::wxDisplaySize

void wxDisplaySize(int *width, int *height)

Gets the physical size of the display in pixels.

Include files

<wx/gdicmn.h>


::wxEnableTopLevelWindows

void wxEnableTopLevelWindow(bool enable = TRUE)

This function enables or disables all top level windows. It is used by ::wxSafeYield.

Include files

<wx/utils.h>


::wxEntry

This initializes wxWindows in a platform-dependent way. Use this if you are not using the default wxWindows entry code (e.g. main or WinMain). For example, you can initialize wxWindows from an Microsoft Foundation Classes application using this function.

void wxEntry(HANDLE hInstance, HANDLE hPrevInstance, const wxString& commandLine, int cmdShow, bool enterLoop = TRUE)

wxWindows initialization under Windows (non-DLL). If enterLoop is FALSE, the function will return immediately after calling wxApp::OnInit. Otherwise, the wxWindows message loop will be entered.

void wxEntry(HANDLE hInstance, HANDLE hPrevInstance, WORD wDataSegment, WORD wHeapSize, const wxString& commandLine)

wxWindows initialization under Windows (for applications constructed as a DLL).

int wxEntry(int argc, const wxString& *argv)

wxWindows initialization under Unix.

Remarks

To clean up wxWindows, call wxApp::OnExit followed by the static function wxApp::CleanUp. For example, if exiting from an MFC application that also uses wxWindows:

int CTheApp::ExitInstance()
{
  // OnExit isn't called by CleanUp so must be called explicitly.
  wxTheApp->OnExit();
  wxApp::CleanUp();

  return CWinApp::ExitInstance();
}
Include files

<wx/app.h>


::wxEndBusyCursor

void wxEndBusyCursor()

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

See also wxIsBusy, wxBusyCursor.

Include files

<wx/utils.h>


::wxError

void wxError(const wxString& msg, const wxString& title = "wxWindows Internal Error")

Displays msg and continues. This writes to standard error under Unix, and pops up a message box under Windows. Used for internal wxWindows errors. See also wxFatalError.

Include files

<wx/utils.h>


::wxExecute

long wxExecute(const wxString& command, bool sync = FALSE, wxProcess *callback = NULL)

long wxExecute(char **argv, bool sync = FALSE, wxProcess *callback = NULL)

long wxExecute(const wxString& command, wxArrayString& output)

long wxExecute(const wxString& command, wxArrayString& output, wxArrayString& errors)

Executes another program in Unix or Windows.

The first form takes a command string, such as "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 sync is FALSE (the default), flow of control immediately returns. If TRUE, 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. The caller should ensure that this can cause no recursion, in the simplest case by calling wxEnableTopLevelWindows(FALSE).

For asynchronous execution, however, the return value is the process id and zero value indicates that the command could not be executed.

If callback isn't NULL and if execution is asynchronous (note that callback parameter can not be non-NULL for synchronous execution), wxProcess::OnTerminate will be called when the process finishes.

Finally, you may use the third overloaded version of this function to execute a process (always synchronously) and capture its output in the array output. The fourth version adds the possibility to additionally capture the messages from standard error output in the errors array.

See also wxShell, wxProcess, Exec sample.

Include files

<wx/utils.h>


::wxExit

void wxExit()

Exits application after calling wxApp::OnExit. Should only be used in an emergency: normally the top-level frame should be deleted (after deleting all other frames) to terminate the application. See wxWindow::OnCloseWindow and wxApp.

Include files

<wx/app.h>


::wxFatalError

void wxFatalError(const wxString& msg, const wxString& title = "wxWindows Fatal Error")

Displays msg and exits. This writes to standard error under Unix, and pops up a message box under Windows. Used for fatal internal wxWindows errors. See also wxError.

Include files

<wx/utils.h>


::wxFindMenuItemId

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

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

Include files

<wx/utils.h>


::wxFindWindowByLabel

wxWindow * wxFindWindowByLabel(const wxString& label, wxWindow *parent=NULL)

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

Include files

<wx/utils.h>


::wxFindWindowByName

wxWindow * wxFindWindowByName(const wxString& name, wxWindow *parent=NULL)

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

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

Include files

<wx/utils.h>


::wxGetActiveWindow

wxWindow * wxGetActiveWindow()

Gets the currently active window (Windows only).

Include files

<wx/windows.h>


::wxGetDisplayName

wxString wxGetDisplayName()

Under X only, returns the current display name. See also wxSetDisplayName.

Include files

<wx/utils.h>


::wxGetHomeDir

wxString wxGetHomeDir()

Return the (current) user's home directory.

See also

wxGetUserHome

Include files

<wx/utils.h>


::wxGetFreeMemory

long wxGetFreeMemory()

Returns the amount of free memory in bytes under environments which support it, and -1 if not supported. Currently, it is supported only under Windows, Linux and Solaris.

Include files

<wx/utils.h>


::wxGetMousePosition

void wxGetMousePosition(int* x, int* y)

Returns the mouse position in screen coordinates.

Include files

<wx/utils.h>


::wxGetOsDescription

wxString wxGetOsDescription()

Returns the string containing the description of the current platform in a user-readable form. For example, this function may return strings like Windows NT Version 4.0 or Linux 2.2.2 i386.

See also

::wxGetOsVersion

Include files

<wx/utils.h>


::wxGetOsVersion

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

Gets operating system version information.

Platform Return types
Macintosh Return value is wxMACINTOSH.
GTK Return value is wxGTK, For GTK 1.0, major is 1, minor is 0.
Motif Return value is wxMOTIF_X, major is X version, minor is X revision.
OS/2 Return value is wxOS2_PM.
Windows 3.1 Return value is wxWINDOWS, major is 3, minor is 1.
Windows NT/2000 Return value is wxWINDOWS_NT, version is returned in major and minor
Windows 98 Return value is wxWIN95, major is 4, minor is 1 or greater.
Windows 95 Return value is wxWIN95, major is 4, minor is 0.
Win32s (Windows 3.1) Return value is wxWIN32S, major is 3, minor is 1.
Watcom C++ 386 supervisor mode (Windows 3.1) Return value is wxWIN386, major is 3, minor is 1.

See also

::wxGetOsDescription

Include files

<wx/utils.h>


::wxGetResource

bool wxGetResource(const wxString& section, const wxString& entry, const wxString& *value, const wxString& file = NULL)

bool wxGetResource(const wxString& section, const wxString& entry, float *value, const wxString& file = NULL)

bool wxGetResource(const wxString& section, const wxString& entry, long *value, const wxString& file = NULL)

bool wxGetResource(const wxString& section, const wxString& entry, int *value, const wxString& file = NULL)

Gets a resource value from the resource database (for example, WIN.INI, or .Xdefaults). If file is NULL, WIN.INI or .Xdefaults is used, otherwise the specified file is used.

Under X, if an application class (wxApp::GetClassName) has been defined, it is appended to the string /usr/lib/X11/app-defaults/ to try to find an applications default file when merging all resource databases.

The reason for passing the result in an argument is that it can be convenient to define a default value, which gets overridden if the value exists in the resource file. It saves a separate test for that resource's existence, and it also allows the overloading of the function for different types.

See also wxWriteResource, wxConfigBase.

Include files

<wx/utils.h>


::wxGetUserId

bool wxGetUserId(const wxString& buf, int bufSize)

Copies the user's login identity (such as "jacs'') into the buffer buf, of maximum size bufSize, returning TRUE if successful. Under Windows, this returns "user''.

Include files

<wx/utils.h>


::wxGetUserHome

const wxChar * wxGetUserHome(const wxString& user = "")

Returns the home directory for the given user. If the username is empty (default value), this function behaves like wxGetHomeDir.

Include files

<wx/utils.h>


::wxGetUserName

bool wxGetUserName(const wxString& buf, int bufSize)

Copies the user's name (such as "Julian Smart'') into the buffer buf, of maximum size bufSize, returning TRUE if successful. Under Windows, this returns "unknown''.

Include files

<wx/utils.h>


::wxHandleFatalExceptions

bool wxHandleFatalExceptions(bool doIt = TRUE)

If doIt is TRUE, the fatal exceptions (also known as general protection faults under Windows or segmentation violations in the Unix world) will be caught and passed to wxApp::OnFatalException. By default, i.e. before this function is called, they will be handled in the normal way which usually just means that the application will be terminated. Calling wxHandleFatalExceptions() with doIt equal to FALSE will restore this default behaviour.


::wxKill

int wxKill(long pid, int sig)

Under Unix (the only supported platform), equivalent to the Unix kill function. Returns 0 on success, -1 on failure.

Tip: sending a signal of 0 to a process returns -1 if the process does not exist. It does not raise a signal in the receiving process.

Include files

<wx/utils.h>


::wxInitAllImageHandlers

void wxInitAllImageHandlers()

Initializes all available image handlers. For a list of available handlers, see wxImage.

See also

wxImage, wxImageHandler


::wxIsBusy

bool wxIsBusy()

Returns TRUE if between two wxBeginBusyCursor and wxEndBusyCursor calls.

See also wxBusyCursor.

Include files

<wx/utils.h>


::wxLoadUserResource

wxString wxLoadUserResource(const wxString& resourceName, const wxString& resourceType="TEXT")

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 .rc file using the following syntax:

myResource TEXT file.ext
where file.ext is a file that the resource compiler can find.

One use of this is to store .wxr files instead of including the data in the C++ file; some compilers cannot cope with the long strings in a .wxr file. The resource data can then be parsed using wxResourceParseString.

This function is available under Windows only.

Include files

<wx/utils.h>


::wxNow

wxString wxNow()

Returns a string representing the current date and time.

Include files

<wx/utils.h>


::wxPostDelete

void wxPostDelete(wxObject *object)

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.

Include files

<wx/utils.h>


::wxPostEvent

void wxPostEvent(wxEvtHandler *dest, wxEvent& event)

This function posts the event to the specified dest object. The difference between sending an event and posting it is that in the first case the event is processed before the function returns (in wxWindows, event sending is done with ProcessEvent function), but in the second, the function returns immediately and the event will be processed sometime later - usually during the next even loop iteration.

Note that a copy of the event is made by the function, so the original copy can be deleted as soon as function returns. This function can also be used to send events between different threads safely. As this function makes a copy of the event, the event needs to have a fully implemented Clone() method, which may not be the case for all event in wxWindows.

See also AddPendingEvent (which this function uses internally).

Include files

<wx/app.h>


::wxSafeYield

bool wxSafeYield(wxWindow* win = NULL)

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

Include files

<wx/utils.h>


::wxSetDisplayName

void wxSetDisplayName(const wxString& displayName)

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

See also wxGetDisplayName.

Include files

<wx/utils.h>


::wxShell

bool wxShell(const wxString& command = NULL)

Executes a command in an interactive shell window. If no command is specified, then just the shell is spawned.

See also wxExecute, Exec sample.

Include files

<wx/utils.h>


::wxSleep

void wxSleep(int secs)

Sleeps for the specified number of seconds.

Include files

<wx/utils.h>


::wxStripMenuCodes

wxString wxStripMenuCodes(const wxString& in)

void wxStripMenuCodes(char* in, char* out)

Strips any menu codes from in and places the result in out (or returns the new string, in the first form).

Menu codes include & (mark the next character with an underline as a keyboard shortkey in Windows and Motif) and \t (tab in Windows).

Include files

<wx/utils.h>


::wxToLower

char wxToLower(char ch)

Converts the character to lower case. This is implemented as a macro for efficiency.

Include files

<wx/utils.h>


::wxToUpper

char wxToUpper(char ch)

Converts the character to upper case. This is implemented as a macro for efficiency.

Include files

<wx/utils.h>


::wxTrace

void wxTrace(const wxString& fmt, ...)

Takes printf-style variable argument syntax. Output is directed to the current output stream (see wxDebugContext).

This function is now obsolete, replaced by Log functions.

Include files

<wx/memory.h>


::wxTraceLevel

void wxTraceLevel(int level, const wxString& fmt, ...)

Takes printf-style variable argument syntax. Output is directed to the current output stream (see wxDebugContext). The first argument should be the level at which this information is appropriate. It will only be output if the level returned by wxDebugContext::GetLevel is equal to or greater than this value.

This function is now obsolete, replaced by Log functions.

Include files

<wx/memory.h>


::wxUsleep

void wxUsleep(unsigned long milliseconds)

Sleeps for the specified number of milliseconds. Notice that usage of this function is encouraged instead of calling usleep(3) directly because the standard usleep() function is not MT safe.

Include files

<wx/utils.h>


::wxWriteResource

bool wxWriteResource(const wxString& section, const wxString& entry, const wxString& value, const wxString& file = NULL)

bool wxWriteResource(const wxString& section, const wxString& entry, float value, const wxString& file = NULL)

bool wxWriteResource(const wxString& section, const wxString& entry, long value, const wxString& file = NULL)

bool wxWriteResource(const wxString& section, const wxString& entry, int value, const wxString& file = NULL)

Writes a resource value into the resource database (for example, WIN.INI, or .Xdefaults). If file is NULL, WIN.INI or .Xdefaults is used, otherwise the specified file is used.

Under X, the resource databases are cached until the internal function wxFlushResources is called automatically on exit, when all updated resource databases are written to their files.

Note that it is considered bad manners to write to the .Xdefaults file under Unix, although the WIN.INI file is fair game under Windows.

See also wxGetResource, wxConfigBase.

Include files

<wx/utils.h>


::wxYield

bool wxYield()

Yields control to pending messages in the windowing system. This can be useful, for example, when a time-consuming process writes to a text window. Without an occasional yield, the text window will not be updated properly, and on systems with cooperative multitasking, such as Windows 3.1 other processes will not respond.

Caution should be exercised, however, since yielding may allow the user to perform actions which are not compatible with the current task. Disabling menu items or whole menus during processing can avoid unwanted reentrance of code: see ::wxSafeYield for a better function.

Note that wxYield will not flush the message logs. This is intentional as calling wxYield is usually done to quickly update the screen and popping up a message box dialog may be undesirable. If you do wish to flush the log messages immediately (otherwise it will be done during the next idle loop iteration), call wxLog::FlushActive.

Include files

<wx/app.h> or <wx/utils.h>


::wxWakeUpIdle

void wxWakeUpIdle()

This functions wakes up the (internal and platform dependent) idle system, i.e. it will force the system to send an idle event even if the system currently is idle and thus would not send any idle event until after some other event would get sent. This is also useful for sending events between two threads and is used by the corresponding functions ::wxPostEvent and wxEvtHandler::AddPendingEvent.

Include files

<wx/app.h>