1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: Miscellaneous utilities
4 // Author: Julian Smart
8 // Copyright: (c) 1998 Julian Smart
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
15 // ----------------------------------------------------------------------------
17 // ----------------------------------------------------------------------------
19 #if defined(__GNUG__) && !defined(NO_GCC_PRAGMA) && !defined(__EMX__)
20 // Some older compilers (such as EMX) cannot handle
21 // #pragma interface/implementation correctly, iff
22 // #pragma implementation is used in _two_ translation
23 // units (as created by e.g. event.cpp compiled for
24 // libwx_base and event.cpp compiled for libwx_gui_core).
25 // So we must not use those pragmas for those compilers in
27 #pragma interface "utils.h"
30 #include "wx/object.h"
32 #include "wx/filefn.h"
34 class WXDLLIMPEXP_BASE wxArrayString
;
36 // need this for wxGetDiskSpace() as we can't, unfortunately, forward declare
38 #include "wx/longlong.h"
47 // ----------------------------------------------------------------------------
48 // Forward declaration
49 // ----------------------------------------------------------------------------
51 class WXDLLIMPEXP_CORE wxProcess
;
52 class WXDLLIMPEXP_CORE wxFrame
;
53 class WXDLLIMPEXP_CORE wxWindow
;
54 class WXDLLIMPEXP_CORE wxWindowList
;
55 class WXDLLIMPEXP_CORE wxPoint
;
57 // ----------------------------------------------------------------------------
59 // ----------------------------------------------------------------------------
61 #define wxMax(a,b) (((a) > (b)) ? (a) : (b))
62 #define wxMin(a,b) (((a) < (b)) ? (a) : (b))
64 // ----------------------------------------------------------------------------
65 // String functions (deprecated, use wxString)
66 // ----------------------------------------------------------------------------
68 // Make a copy of this string using 'new'
69 #if WXWIN_COMPATIBILITY_2_4
70 WXDLLIMPEXP_BASE wxChar
* copystring(const wxChar
*s
);
73 // A shorter way of using strcmp
74 #define wxStringEq(s1, s2) (s1 && s2 && (wxStrcmp(s1, s2) == 0))
76 // ----------------------------------------------------------------------------
77 // Miscellaneous functions
78 // ----------------------------------------------------------------------------
81 WXDLLIMPEXP_BASE
void wxBell();
83 // Get OS description as a user-readable string
84 WXDLLIMPEXP_BASE wxString
wxGetOsDescription();
87 WXDLLIMPEXP_BASE
int wxGetOsVersion(int *majorVsn
= (int *) NULL
,
88 int *minorVsn
= (int *) NULL
);
90 // Return a string with the current date/time
91 WXDLLIMPEXP_BASE wxString
wxNow();
93 // Return path where wxWidgets is installed (mostly useful in Unices)
94 WXDLLIMPEXP_BASE
const wxChar
*wxGetInstallPrefix();
95 // Return path to wxWin data (/usr/share/wx/%{version}) (Unices)
96 WXDLLIMPEXP_BASE wxString
wxGetDataDir();
101 // Get the state of a key (true if pressed, false if not)
102 // This is generally most useful getting the state of
103 // the modifier or toggle keys.
104 WXDLLEXPORT
bool wxGetKeyState(wxKeyCode key
);
107 // Don't synthesize KeyUp events holding down a key and producing
108 // KeyDown events with autorepeat. On by default and always on
110 WXDLLEXPORT
bool wxSetDetectableAutoRepeat( bool flag
);
112 // ----------------------------------------------------------------------------
113 // Window ID management
114 // ----------------------------------------------------------------------------
116 // Generate a unique ID
117 WXDLLEXPORT
long wxNewId();
119 // Ensure subsequent IDs don't clash with this one
120 WXDLLEXPORT
void wxRegisterId(long id
);
122 // Return the current ID
123 WXDLLEXPORT
long wxGetCurrentId();
127 // ----------------------------------------------------------------------------
128 // Various conversions
129 // ----------------------------------------------------------------------------
131 // these functions are deprecated, use wxString methods instead!
132 #if WXWIN_COMPATIBILITY_2_4
134 WXDLLIMPEXP_DATA_BASE(extern const wxChar
*) wxFloatToStringStr
;
135 WXDLLIMPEXP_DATA_BASE(extern const wxChar
*) wxDoubleToStringStr
;
137 WXDLLIMPEXP_BASE
void StringToFloat(const wxChar
*s
, float *number
);
138 WXDLLIMPEXP_BASE wxChar
* FloatToString(float number
, const wxChar
*fmt
= wxFloatToStringStr
);
139 WXDLLIMPEXP_BASE
void StringToDouble(const wxChar
*s
, double *number
);
140 WXDLLIMPEXP_BASE wxChar
* DoubleToString(double number
, const wxChar
*fmt
= wxDoubleToStringStr
);
141 WXDLLIMPEXP_BASE
void StringToInt(const wxChar
*s
, int *number
);
142 WXDLLIMPEXP_BASE
void StringToLong(const wxChar
*s
, long *number
);
143 WXDLLIMPEXP_BASE wxChar
* IntToString(int number
);
144 WXDLLIMPEXP_BASE wxChar
* LongToString(long number
);
146 #endif // WXWIN_COMPATIBILITY_2_4
148 // Convert 2-digit hex number to decimal
149 WXDLLIMPEXP_BASE
int wxHexToDec(const wxString
& buf
);
151 // Convert decimal integer to 2-character hex string
152 WXDLLIMPEXP_BASE
void wxDecToHex(int dec
, wxChar
*buf
);
153 WXDLLIMPEXP_BASE wxString
wxDecToHex(int dec
);
155 // ----------------------------------------------------------------------------
156 // Process management
157 // ----------------------------------------------------------------------------
159 // NB: for backwards compatibility reasons the values of wxEXEC_[A]SYNC *must*
160 // be 0 and 1, don't change!
164 // execute the process asynchronously
167 // execute it synchronously, i.e. wait until it finishes
170 // under Windows, don't hide the child even if it's IO is redirected (this
171 // is done by default)
174 // under Unix, if the process is the group leader then passing wxKILL_CHILDREN to wxKill
175 // kills all children as well as pid
176 wxEXEC_MAKE_GROUP_LEADER
= 4,
178 // by default synchronous execution disables all program windows to avoid
179 // that the user interacts with the program while the child process is
180 // running, you can use this flag to prevent this from happening
184 // Execute another program.
186 // If flags contain wxEXEC_SYNC, return -1 on failure and the exit code of the
187 // process if everything was ok. Otherwise (i.e. if wxEXEC_ASYNC), return 0 on
188 // failure and the PID of the launched process if ok.
189 WXDLLIMPEXP_BASE
long wxExecute(wxChar
**argv
, int flags
= wxEXEC_ASYNC
,
190 wxProcess
*process
= (wxProcess
*) NULL
);
191 WXDLLIMPEXP_BASE
long wxExecute(const wxString
& command
, int flags
= wxEXEC_ASYNC
,
192 wxProcess
*process
= (wxProcess
*) NULL
);
194 // execute the command capturing its output into an array line by line, this is
195 // always synchronous
196 WXDLLIMPEXP_BASE
long wxExecute(const wxString
& command
,
197 wxArrayString
& output
);
199 // also capture stderr (also synchronous)
200 WXDLLIMPEXP_BASE
long wxExecute(const wxString
& command
,
201 wxArrayString
& output
,
202 wxArrayString
& error
);
206 wxSIGNONE
= 0, // verify if the process exists under Unix
213 wxSIGIOT
= wxSIGABRT
, // another name
224 // further signals are different in meaning between different Unix systems
229 wxKILL_OK
, // no error
230 wxKILL_BAD_SIGNAL
, // no such signal
231 wxKILL_ACCESS_DENIED
, // permission denied
232 wxKILL_NO_PROCESS
, // no such process
233 wxKILL_ERROR
// another, unspecified error
238 wxKILL_NOCHILDREN
= 0, // don't kill children
239 wxKILL_CHILDREN
= 1 // kill children
244 wxSHUTDOWN_POWEROFF
, // power off the computer
245 wxSHUTDOWN_REBOOT
// shutdown and reboot
248 // Shutdown or reboot the PC
249 WXDLLIMPEXP_BASE
bool wxShutdown(wxShutdownFlags wFlags
);
251 // send the given signal to the process (only NONE and KILL are supported under
252 // Windows, all others mean TERM), return 0 if ok and -1 on error
254 // return detailed error in rc if not NULL
255 WXDLLIMPEXP_BASE
int wxKill(long pid
,
256 wxSignal sig
= wxSIGTERM
,
257 wxKillError
*rc
= NULL
,
258 int flags
= wxKILL_NOCHILDREN
);
260 // Execute a command in an interactive shell window (always synchronously)
261 // If no command then just the shell
262 WXDLLIMPEXP_BASE
bool wxShell(const wxString
& command
= wxEmptyString
);
264 // As wxShell(), but must give a (non interactive) command and its output will
265 // be returned in output array
266 WXDLLIMPEXP_BASE
bool wxShell(const wxString
& command
, wxArrayString
& output
);
268 // Sleep for nSecs seconds
269 WXDLLIMPEXP_BASE
void wxSleep(int nSecs
);
271 // Sleep for a given amount of milliseconds
272 WXDLLIMPEXP_BASE
void wxMilliSleep(unsigned long milliseconds
);
274 // Sleep for a given amount of microseconds
275 WXDLLIMPEXP_BASE
void wxMicroSleep(unsigned long microseconds
);
277 // Sleep for a given amount of milliseconds (old, bad name), use wxMilliSleep
278 wxDEPRECATED( WXDLLIMPEXP_BASE
void wxUsleep(unsigned long milliseconds
) );
280 // Get the process id of the current process
281 WXDLLIMPEXP_BASE
unsigned long wxGetProcessId();
283 // Get free memory in bytes, or -1 if cannot determine amount (e.g. on UNIX)
284 WXDLLIMPEXP_BASE
long wxGetFreeMemory();
286 // should wxApp::OnFatalException() be called?
287 WXDLLIMPEXP_BASE
bool wxHandleFatalExceptions(bool doit
= true);
289 // ----------------------------------------------------------------------------
290 // Environment variables
291 // ----------------------------------------------------------------------------
293 // returns true if variable exists (value may be NULL if you just want to check
295 WXDLLIMPEXP_BASE
bool wxGetEnv(const wxString
& var
, wxString
*value
);
297 // set the env var name to the given value, return true on success
298 WXDLLIMPEXP_BASE
bool wxSetEnv(const wxString
& var
, const wxChar
*value
);
300 // remove the env var from environment
301 inline bool wxUnsetEnv(const wxString
& var
) { return wxSetEnv(var
, NULL
); }
303 // ----------------------------------------------------------------------------
304 // Network and username functions.
305 // ----------------------------------------------------------------------------
307 // NB: "char *" functions are deprecated, use wxString ones!
310 WXDLLIMPEXP_BASE
bool wxGetEmailAddress(wxChar
*buf
, int maxSize
);
311 WXDLLIMPEXP_BASE wxString
wxGetEmailAddress();
314 WXDLLIMPEXP_BASE
bool wxGetHostName(wxChar
*buf
, int maxSize
);
315 WXDLLIMPEXP_BASE wxString
wxGetHostName();
318 WXDLLIMPEXP_BASE wxString
wxGetFullHostName();
319 WXDLLIMPEXP_BASE
bool wxGetFullHostName(wxChar
*buf
, int maxSize
);
321 // Get user ID e.g. jacs (this is known as login name under Unix)
322 WXDLLIMPEXP_BASE
bool wxGetUserId(wxChar
*buf
, int maxSize
);
323 WXDLLIMPEXP_BASE wxString
wxGetUserId();
325 // Get user name e.g. Julian Smart
326 WXDLLIMPEXP_BASE
bool wxGetUserName(wxChar
*buf
, int maxSize
);
327 WXDLLIMPEXP_BASE wxString
wxGetUserName();
329 // Get current Home dir and copy to dest (returns pstr->c_str())
330 WXDLLIMPEXP_BASE wxString
wxGetHomeDir();
331 WXDLLIMPEXP_BASE
const wxChar
* wxGetHomeDir(wxString
*pstr
);
333 // Get the user's home dir (caller must copy --- volatile)
334 // returns NULL is no HOME dir is known
335 #if defined(__UNIX__) && wxUSE_UNICODE
336 WXDLLIMPEXP_BASE
const wxMB2WXbuf
wxGetUserHome(const wxString
& user
= wxEmptyString
);
338 WXDLLIMPEXP_BASE wxChar
* wxGetUserHome(const wxString
& user
= wxEmptyString
);
341 // get number of total/free bytes on the disk where path belongs
342 WXDLLIMPEXP_BASE
bool wxGetDiskSpace(const wxString
& path
,
343 wxLongLong
*pTotal
= NULL
,
344 wxLongLong
*pFree
= NULL
);
346 #if wxUSE_GUI // GUI only things from now on
348 // ----------------------------------------------------------------------------
349 // Menu accelerators related things
350 // ----------------------------------------------------------------------------
352 WXDLLEXPORT wxChar
* wxStripMenuCodes(const wxChar
*in
, wxChar
*out
= (wxChar
*) NULL
);
353 WXDLLEXPORT wxString
wxStripMenuCodes(const wxString
& str
);
356 class WXDLLEXPORT wxAcceleratorEntry
;
357 WXDLLEXPORT wxAcceleratorEntry
*wxGetAccelFromString(const wxString
& label
);
358 #endif // wxUSE_ACCEL
360 // ----------------------------------------------------------------------------
362 // ----------------------------------------------------------------------------
364 // Returns menu item id or wxNOT_FOUND if none.
365 WXDLLEXPORT
int wxFindMenuItemId(wxFrame
*frame
, const wxString
& menuString
, const wxString
& itemString
);
367 // Find the wxWindow at the given point. wxGenericFindWindowAtPoint
368 // is always present but may be less reliable than a native version.
369 WXDLLEXPORT wxWindow
* wxGenericFindWindowAtPoint(const wxPoint
& pt
);
370 WXDLLEXPORT wxWindow
* wxFindWindowAtPoint(const wxPoint
& pt
);
372 // NB: this function is obsolete, use wxWindow::FindWindowByLabel() instead
374 // Find the window/widget with the given title or label.
375 // Pass a parent to begin the search from, or NULL to look through
377 WXDLLEXPORT wxWindow
* wxFindWindowByLabel(const wxString
& title
, wxWindow
*parent
= (wxWindow
*) NULL
);
379 // NB: this function is obsolete, use wxWindow::FindWindowByName() instead
381 // Find window by name, and if that fails, by label.
382 WXDLLEXPORT wxWindow
* wxFindWindowByName(const wxString
& name
, wxWindow
*parent
= (wxWindow
*) NULL
);
384 // ----------------------------------------------------------------------------
385 // Message/event queue helpers
386 // ----------------------------------------------------------------------------
388 // Yield to other apps/messages and disable user input
389 WXDLLEXPORT
bool wxSafeYield(wxWindow
*win
= NULL
, bool onlyIfNeeded
= false);
391 // Enable or disable input to all top level windows
392 WXDLLEXPORT
void wxEnableTopLevelWindows(bool enable
= true);
394 // Check whether this window wants to process messages, e.g. Stop button
395 // in long calculations.
396 WXDLLEXPORT
bool wxCheckForInterrupt(wxWindow
*wnd
);
398 // Consume all events until no more left
399 WXDLLEXPORT
void wxFlushEvents();
401 // a class which disables all windows (except, may be, thegiven one) in its
402 // ctor and enables them back in its dtor
403 class WXDLLEXPORT wxWindowDisabler
406 wxWindowDisabler(wxWindow
*winToSkip
= (wxWindow
*)NULL
);
410 wxWindowList
*m_winDisabled
;
412 DECLARE_NO_COPY_CLASS(wxWindowDisabler
)
415 // ----------------------------------------------------------------------------
417 // ----------------------------------------------------------------------------
419 // Set the cursor to the busy cursor for all windows
420 class WXDLLEXPORT wxCursor
;
421 WXDLLEXPORT_DATA(extern wxCursor
*) wxHOURGLASS_CURSOR
;
422 WXDLLEXPORT
void wxBeginBusyCursor(wxCursor
*cursor
= wxHOURGLASS_CURSOR
);
424 // Restore cursor to normal
425 WXDLLEXPORT
void wxEndBusyCursor();
427 // true if we're between the above two calls
428 WXDLLEXPORT
bool wxIsBusy();
430 // Convenience class so we can just create a wxBusyCursor object on the stack
431 class WXDLLEXPORT wxBusyCursor
434 wxBusyCursor(wxCursor
* cursor
= wxHOURGLASS_CURSOR
)
435 { wxBeginBusyCursor(cursor
); }
437 { wxEndBusyCursor(); }
439 // FIXME: These two methods are currently only implemented (and needed?)
440 // in wxGTK. BusyCursor handling should probably be moved to
441 // common code since the wxGTK and wxMSW implementations are very
442 // similar except for wxMSW using HCURSOR directly instead of
444 static const wxCursor
&GetStoredCursor();
445 static const wxCursor
GetBusyCursor();
449 // ----------------------------------------------------------------------------
450 // Reading and writing resources (eg WIN.INI, .Xdefaults)
451 // ----------------------------------------------------------------------------
454 WXDLLEXPORT
bool wxWriteResource(const wxString
& section
, const wxString
& entry
, const wxString
& value
, const wxString
& file
= wxEmptyString
);
455 WXDLLEXPORT
bool wxWriteResource(const wxString
& section
, const wxString
& entry
, float value
, const wxString
& file
= wxEmptyString
);
456 WXDLLEXPORT
bool wxWriteResource(const wxString
& section
, const wxString
& entry
, long value
, const wxString
& file
= wxEmptyString
);
457 WXDLLEXPORT
bool wxWriteResource(const wxString
& section
, const wxString
& entry
, int value
, const wxString
& file
= wxEmptyString
);
459 WXDLLEXPORT
bool wxGetResource(const wxString
& section
, const wxString
& entry
, wxChar
**value
, const wxString
& file
= wxEmptyString
);
460 WXDLLEXPORT
bool wxGetResource(const wxString
& section
, const wxString
& entry
, float *value
, const wxString
& file
= wxEmptyString
);
461 WXDLLEXPORT
bool wxGetResource(const wxString
& section
, const wxString
& entry
, long *value
, const wxString
& file
= wxEmptyString
);
462 WXDLLEXPORT
bool wxGetResource(const wxString
& section
, const wxString
& entry
, int *value
, const wxString
& file
= wxEmptyString
);
463 #endif // wxUSE_RESOURCES
465 void WXDLLEXPORT
wxGetMousePosition( int* x
, int* y
);
467 // MSW only: get user-defined resource from the .res file.
468 // Returns NULL or newly-allocated memory, so use delete[] to clean up.
470 WXDLLEXPORT
extern const wxChar
* wxUserResourceStr
;
471 WXDLLEXPORT wxChar
* wxLoadUserResource(const wxString
& resourceName
, const wxString
& resourceType
= wxUserResourceStr
);
474 // ----------------------------------------------------------------------------
475 // Display and colorss (X only)
476 // ----------------------------------------------------------------------------
479 void *wxGetDisplay();
483 WXDisplay
*wxGetDisplay();
484 bool wxSetDisplay(const wxString
& display_name
);
485 wxString
wxGetDisplayName();
490 #ifdef __VMS__ // Xlib.h for VMS is not (yet) compatible with C++
491 // The resulting warnings are switched off here
492 #pragma message disable nosimpint
494 // #include <X11/Xlib.h>
496 #pragma message enable nosimpint
503 // ----------------------------------------------------------------------------
504 // wxYield(): these functions are obsolete, please use wxApp methods instead!
505 // ----------------------------------------------------------------------------
507 // Yield to other apps/messages
508 WXDLLIMPEXP_BASE
bool wxYield();
510 // Like wxYield, but fails silently if the yield is recursive.
511 WXDLLIMPEXP_BASE
bool wxYieldIfNeeded();
513 // ----------------------------------------------------------------------------
514 // Error message functions used by wxWidgets (deprecated, use wxLog)
515 // ----------------------------------------------------------------------------
517 #if WXWIN_COMPATIBILITY_2_2
519 // Format a message on the standard error (UNIX) or the debugging
521 WXDLLIMPEXP_BASE
void wxDebugMsg(const wxChar
*fmt
...) ATTRIBUTE_PRINTF_1
;
523 // Non-fatal error (continues)
524 WXDLLIMPEXP_DATA_BASE(extern const wxChar
*) wxInternalErrorStr
;
525 WXDLLIMPEXP_BASE
void wxError(const wxString
& msg
, const wxString
& title
= wxInternalErrorStr
);
527 // Fatal error (exits)
528 WXDLLIMPEXP_DATA_BASE(extern const wxChar
*) wxFatalErrorStr
;
529 WXDLLIMPEXP_BASE
void wxFatalError(const wxString
& msg
, const wxString
& title
= wxFatalErrorStr
);
531 #endif // WXWIN_COMPATIBILITY_2_2