1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: Miscellaneous utilities
4 // Author: Julian Smart
8 // Copyright: (c) 1998 Julian Smart
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
15 // ----------------------------------------------------------------------------
17 // ----------------------------------------------------------------------------
19 #include "wx/object.h"
21 #include "wx/filefn.h"
23 class WXDLLIMPEXP_BASE wxArrayString
;
25 // need this for wxGetDiskSpace() as we can't, unfortunately, forward declare
27 #include "wx/longlong.h"
38 // ----------------------------------------------------------------------------
39 // Forward declaration
40 // ----------------------------------------------------------------------------
42 class WXDLLIMPEXP_CORE wxProcess
;
43 class WXDLLIMPEXP_CORE wxFrame
;
44 class WXDLLIMPEXP_CORE wxWindow
;
45 class WXDLLIMPEXP_CORE wxWindowList
;
46 class WXDLLIMPEXP_CORE wxPoint
;
48 // ----------------------------------------------------------------------------
50 // ----------------------------------------------------------------------------
52 #define wxMax(a,b) (((a) > (b)) ? (a) : (b))
53 #define wxMin(a,b) (((a) < (b)) ? (a) : (b))
55 // wxGetFreeMemory can return huge amount of memory on 64-bit platforms
56 // define wxMemorySize according to the type which best fits your platform
57 #if wxUSE_LONGLONG && defined(__WIN64__)
58 // 64 bit Windowses have sizeof(long) only 32 bit long
59 // we need to use wxLongLong to express memory sizes
60 #define wxMemorySize wxLongLong
62 // 64 bit UNIX has sizeof(long) = 64
63 // assume 32 bit platforms cannnot return more than 32bits of
64 #define wxMemorySize long
67 // ----------------------------------------------------------------------------
68 // String functions (deprecated, use wxString)
69 // ----------------------------------------------------------------------------
71 // Make a copy of this string using 'new'
72 #if WXWIN_COMPATIBILITY_2_4
73 wxDEPRECATED( WXDLLIMPEXP_BASE wxChar
* copystring(const wxChar
*s
) );
76 // A shorter way of using strcmp
77 #define wxStringEq(s1, s2) (s1 && s2 && (wxStrcmp(s1, s2) == 0))
79 // ----------------------------------------------------------------------------
80 // Miscellaneous functions
81 // ----------------------------------------------------------------------------
84 #if !defined __EMX__ && \
85 (defined __WXMOTIF__ || defined __WXGTK__ || defined __WXX11__)
86 WXDLLIMPEXP_CORE
void wxBell();
88 WXDLLIMPEXP_BASE
void wxBell();
91 // Get OS description as a user-readable string
92 WXDLLIMPEXP_BASE wxString
wxGetOsDescription();
95 WXDLLIMPEXP_BASE
int wxGetOsVersion(int *majorVsn
= (int *) NULL
,
96 int *minorVsn
= (int *) NULL
);
98 // Return a string with the current date/time
99 WXDLLIMPEXP_BASE wxString
wxNow();
101 // Return path where wxWidgets is installed (mostly useful in Unices)
102 WXDLLIMPEXP_BASE
const wxChar
*wxGetInstallPrefix();
103 // Return path to wxWin data (/usr/share/wx/%{version}) (Unices)
104 WXDLLIMPEXP_BASE wxString
wxGetDataDir();
109 // Get the state of a key (true if pressed, false if not)
110 // This is generally most useful getting the state of
111 // the modifier or toggle keys.
112 WXDLLEXPORT
bool wxGetKeyState(wxKeyCode key
);
115 // Don't synthesize KeyUp events holding down a key and producing
116 // KeyDown events with autorepeat. On by default and always on
118 WXDLLEXPORT
bool wxSetDetectableAutoRepeat( bool flag
);
120 // ----------------------------------------------------------------------------
121 // Window ID management
122 // ----------------------------------------------------------------------------
124 // Generate a unique ID
125 WXDLLEXPORT
long wxNewId();
127 // Ensure subsequent IDs don't clash with this one
128 WXDLLEXPORT
void wxRegisterId(long id
);
130 // Return the current ID
131 WXDLLEXPORT
long wxGetCurrentId();
135 // ----------------------------------------------------------------------------
136 // Various conversions
137 // ----------------------------------------------------------------------------
139 // these functions are deprecated, use wxString methods instead!
140 #if WXWIN_COMPATIBILITY_2_4
142 extern WXDLLIMPEXP_DATA_BASE(const wxChar
*) wxFloatToStringStr
;
143 extern WXDLLIMPEXP_DATA_BASE(const wxChar
*) wxDoubleToStringStr
;
145 wxDEPRECATED( WXDLLIMPEXP_BASE
void StringToFloat(const wxChar
*s
, float *number
) );
146 wxDEPRECATED( WXDLLIMPEXP_BASE wxChar
* FloatToString(float number
, const wxChar
*fmt
= wxFloatToStringStr
) );
147 wxDEPRECATED( WXDLLIMPEXP_BASE
void StringToDouble(const wxChar
*s
, double *number
) );
148 wxDEPRECATED( WXDLLIMPEXP_BASE wxChar
* DoubleToString(double number
, const wxChar
*fmt
= wxDoubleToStringStr
) );
149 wxDEPRECATED( WXDLLIMPEXP_BASE
void StringToInt(const wxChar
*s
, int *number
) );
150 wxDEPRECATED( WXDLLIMPEXP_BASE
void StringToLong(const wxChar
*s
, long *number
) );
151 wxDEPRECATED( WXDLLIMPEXP_BASE wxChar
* IntToString(int number
) );
152 wxDEPRECATED( WXDLLIMPEXP_BASE wxChar
* LongToString(long number
) );
154 #endif // WXWIN_COMPATIBILITY_2_4
156 // Convert 2-digit hex number to decimal
157 WXDLLIMPEXP_BASE
int wxHexToDec(const wxString
& buf
);
159 // Convert decimal integer to 2-character hex string
160 WXDLLIMPEXP_BASE
void wxDecToHex(int dec
, wxChar
*buf
);
161 WXDLLIMPEXP_BASE wxString
wxDecToHex(int dec
);
163 // ----------------------------------------------------------------------------
164 // Process management
165 // ----------------------------------------------------------------------------
167 // NB: for backwards compatibility reasons the values of wxEXEC_[A]SYNC *must*
168 // be 0 and 1, don't change!
172 // execute the process asynchronously
175 // execute it synchronously, i.e. wait until it finishes
178 // under Windows, don't hide the child even if it's IO is redirected (this
179 // is done by default)
182 // under Unix, if the process is the group leader then passing wxKILL_CHILDREN to wxKill
183 // kills all children as well as pid
184 wxEXEC_MAKE_GROUP_LEADER
= 4,
186 // by default synchronous execution disables all program windows to avoid
187 // that the user interacts with the program while the child process is
188 // running, you can use this flag to prevent this from happening
192 // Execute another program.
194 // If flags contain wxEXEC_SYNC, return -1 on failure and the exit code of the
195 // process if everything was ok. Otherwise (i.e. if wxEXEC_ASYNC), return 0 on
196 // failure and the PID of the launched process if ok.
197 WXDLLIMPEXP_BASE
long wxExecute(wxChar
**argv
, int flags
= wxEXEC_ASYNC
,
198 wxProcess
*process
= (wxProcess
*) NULL
);
199 WXDLLIMPEXP_BASE
long wxExecute(const wxString
& command
, int flags
= wxEXEC_ASYNC
,
200 wxProcess
*process
= (wxProcess
*) NULL
);
202 // execute the command capturing its output into an array line by line, this is
203 // always synchronous
204 WXDLLIMPEXP_BASE
long wxExecute(const wxString
& command
,
205 wxArrayString
& output
,
208 // also capture stderr (also synchronous)
209 WXDLLIMPEXP_BASE
long wxExecute(const wxString
& command
,
210 wxArrayString
& output
,
211 wxArrayString
& error
,
214 #if defined(__WXMSW__) && wxUSE_IPC
215 // ask a DDE server to execute the DDE request with given parameters
216 WXDLLIMPEXP_BASE
bool wxExecuteDDE(const wxString
& ddeServer
,
217 const wxString
& ddeTopic
,
218 const wxString
& ddeCommand
);
219 #endif // __WXMSW__ && wxUSE_IPC
223 wxSIGNONE
= 0, // verify if the process exists under Unix
230 wxSIGIOT
= wxSIGABRT
, // another name
241 // further signals are different in meaning between different Unix systems
246 wxKILL_OK
, // no error
247 wxKILL_BAD_SIGNAL
, // no such signal
248 wxKILL_ACCESS_DENIED
, // permission denied
249 wxKILL_NO_PROCESS
, // no such process
250 wxKILL_ERROR
// another, unspecified error
255 wxKILL_NOCHILDREN
= 0, // don't kill children
256 wxKILL_CHILDREN
= 1 // kill children
261 wxSHUTDOWN_POWEROFF
, // power off the computer
262 wxSHUTDOWN_REBOOT
// shutdown and reboot
265 // Shutdown or reboot the PC
266 WXDLLIMPEXP_BASE
bool wxShutdown(wxShutdownFlags wFlags
);
275 WXDLLIMPEXP_BASE wxPowerType
wxGetPowerType();
279 wxBATTERY_NORMAL_STATE
, // system is fully usable
280 wxBATTERY_LOW_STATE
, // start to worry
281 wxBATTERY_CRITICAL_STATE
, // save quickly
282 wxBATTERY_SHUTDOWN_STATE
, // too late
283 wxBATTERY_UNKNOWN_STATE
286 WXDLLIMPEXP_BASE wxBatteryState
wxGetBatteryState();
288 // send the given signal to the process (only NONE and KILL are supported under
289 // Windows, all others mean TERM), return 0 if ok and -1 on error
291 // return detailed error in rc if not NULL
292 WXDLLIMPEXP_BASE
int wxKill(long pid
,
293 wxSignal sig
= wxSIGTERM
,
294 wxKillError
*rc
= NULL
,
295 int flags
= wxKILL_NOCHILDREN
);
297 // Execute a command in an interactive shell window (always synchronously)
298 // If no command then just the shell
299 WXDLLIMPEXP_BASE
bool wxShell(const wxString
& command
= wxEmptyString
);
301 // As wxShell(), but must give a (non interactive) command and its output will
302 // be returned in output array
303 WXDLLIMPEXP_BASE
bool wxShell(const wxString
& command
, wxArrayString
& output
);
305 // Sleep for nSecs seconds
306 WXDLLIMPEXP_BASE
void wxSleep(int nSecs
);
308 // Sleep for a given amount of milliseconds
309 WXDLLIMPEXP_BASE
void wxMilliSleep(unsigned long milliseconds
);
311 // Sleep for a given amount of microseconds
312 WXDLLIMPEXP_BASE
void wxMicroSleep(unsigned long microseconds
);
314 // Sleep for a given amount of milliseconds (old, bad name), use wxMilliSleep
315 wxDEPRECATED( WXDLLIMPEXP_BASE
void wxUsleep(unsigned long milliseconds
) );
317 // Get the process id of the current process
318 WXDLLIMPEXP_BASE
unsigned long wxGetProcessId();
320 // Get free memory in bytes, or -1 if cannot determine amount (e.g. on UNIX)
321 WXDLLIMPEXP_BASE wxMemorySize
wxGetFreeMemory();
323 #if wxUSE_ON_FATAL_EXCEPTION
325 // should wxApp::OnFatalException() be called?
326 WXDLLIMPEXP_BASE
bool wxHandleFatalExceptions(bool doit
= true);
328 #endif // wxUSE_ON_FATAL_EXCEPTION
330 // flags for wxLaunchDefaultBrowser
333 wxBROWSER_NEW_WINDOW
= 1
336 // Launch url in the user's default internet browser
337 WXDLLIMPEXP_BASE
bool wxLaunchDefaultBrowser(const wxString
& url
, int flags
= 0);
339 // ----------------------------------------------------------------------------
340 // Environment variables
341 // ----------------------------------------------------------------------------
343 // returns true if variable exists (value may be NULL if you just want to check
345 WXDLLIMPEXP_BASE
bool wxGetEnv(const wxString
& var
, wxString
*value
);
347 // set the env var name to the given value, return true on success
348 WXDLLIMPEXP_BASE
bool wxSetEnv(const wxString
& var
, const wxChar
*value
);
350 // remove the env var from environment
351 inline bool wxUnsetEnv(const wxString
& var
) { return wxSetEnv(var
, NULL
); }
353 // ----------------------------------------------------------------------------
354 // Network and username functions.
355 // ----------------------------------------------------------------------------
357 // NB: "char *" functions are deprecated, use wxString ones!
360 WXDLLIMPEXP_BASE
bool wxGetEmailAddress(wxChar
*buf
, int maxSize
);
361 WXDLLIMPEXP_BASE wxString
wxGetEmailAddress();
364 WXDLLIMPEXP_BASE
bool wxGetHostName(wxChar
*buf
, int maxSize
);
365 WXDLLIMPEXP_BASE wxString
wxGetHostName();
368 WXDLLIMPEXP_BASE wxString
wxGetFullHostName();
369 WXDLLIMPEXP_BASE
bool wxGetFullHostName(wxChar
*buf
, int maxSize
);
371 // Get user ID e.g. jacs (this is known as login name under Unix)
372 WXDLLIMPEXP_BASE
bool wxGetUserId(wxChar
*buf
, int maxSize
);
373 WXDLLIMPEXP_BASE wxString
wxGetUserId();
375 // Get user name e.g. Julian Smart
376 WXDLLIMPEXP_BASE
bool wxGetUserName(wxChar
*buf
, int maxSize
);
377 WXDLLIMPEXP_BASE wxString
wxGetUserName();
379 // Get current Home dir and copy to dest (returns pstr->c_str())
380 WXDLLIMPEXP_BASE wxString
wxGetHomeDir();
381 WXDLLIMPEXP_BASE
const wxChar
* wxGetHomeDir(wxString
*pstr
);
383 // Get the user's home dir (caller must copy --- volatile)
384 // returns NULL is no HOME dir is known
385 #if defined(__UNIX__) && wxUSE_UNICODE
386 WXDLLIMPEXP_BASE
const wxMB2WXbuf
wxGetUserHome(const wxString
& user
= wxEmptyString
);
388 WXDLLIMPEXP_BASE wxChar
* wxGetUserHome(const wxString
& user
= wxEmptyString
);
391 // get number of total/free bytes on the disk where path belongs
392 WXDLLIMPEXP_BASE
bool wxGetDiskSpace(const wxString
& path
,
393 wxLongLong
*pTotal
= NULL
,
394 wxLongLong
*pFree
= NULL
);
396 #if wxUSE_GUI // GUI only things from now on
398 // ----------------------------------------------------------------------------
399 // Menu accelerators related things
400 // ----------------------------------------------------------------------------
402 WXDLLEXPORT wxChar
* wxStripMenuCodes(const wxChar
*in
, wxChar
*out
= (wxChar
*) NULL
);
403 WXDLLEXPORT wxString
wxStripMenuCodes(const wxString
& str
);
406 class WXDLLEXPORT wxAcceleratorEntry
;
407 WXDLLEXPORT wxAcceleratorEntry
*wxGetAccelFromString(const wxString
& label
);
408 #endif // wxUSE_ACCEL
410 // ----------------------------------------------------------------------------
412 // ----------------------------------------------------------------------------
414 // Returns menu item id or wxNOT_FOUND if none.
415 WXDLLEXPORT
int wxFindMenuItemId(wxFrame
*frame
, const wxString
& menuString
, const wxString
& itemString
);
417 // Find the wxWindow at the given point. wxGenericFindWindowAtPoint
418 // is always present but may be less reliable than a native version.
419 WXDLLEXPORT wxWindow
* wxGenericFindWindowAtPoint(const wxPoint
& pt
);
420 WXDLLEXPORT wxWindow
* wxFindWindowAtPoint(const wxPoint
& pt
);
422 // NB: this function is obsolete, use wxWindow::FindWindowByLabel() instead
424 // Find the window/widget with the given title or label.
425 // Pass a parent to begin the search from, or NULL to look through
427 WXDLLEXPORT wxWindow
* wxFindWindowByLabel(const wxString
& title
, wxWindow
*parent
= (wxWindow
*) NULL
);
429 // NB: this function is obsolete, use wxWindow::FindWindowByName() instead
431 // Find window by name, and if that fails, by label.
432 WXDLLEXPORT wxWindow
* wxFindWindowByName(const wxString
& name
, wxWindow
*parent
= (wxWindow
*) NULL
);
434 // ----------------------------------------------------------------------------
435 // Message/event queue helpers
436 // ----------------------------------------------------------------------------
438 // Yield to other apps/messages and disable user input
439 WXDLLEXPORT
bool wxSafeYield(wxWindow
*win
= NULL
, bool onlyIfNeeded
= false);
441 // Enable or disable input to all top level windows
442 WXDLLEXPORT
void wxEnableTopLevelWindows(bool enable
= true);
444 // Check whether this window wants to process messages, e.g. Stop button
445 // in long calculations.
446 WXDLLEXPORT
bool wxCheckForInterrupt(wxWindow
*wnd
);
448 // Consume all events until no more left
449 WXDLLEXPORT
void wxFlushEvents();
451 // a class which disables all windows (except, may be, thegiven one) in its
452 // ctor and enables them back in its dtor
453 class WXDLLEXPORT wxWindowDisabler
456 wxWindowDisabler(wxWindow
*winToSkip
= (wxWindow
*)NULL
);
460 wxWindowList
*m_winDisabled
;
462 DECLARE_NO_COPY_CLASS(wxWindowDisabler
)
465 // ----------------------------------------------------------------------------
467 // ----------------------------------------------------------------------------
469 // Set the cursor to the busy cursor for all windows
470 class WXDLLEXPORT wxCursor
;
471 extern WXDLLEXPORT_DATA(wxCursor
*) wxHOURGLASS_CURSOR
;
472 WXDLLEXPORT
void wxBeginBusyCursor(wxCursor
*cursor
= wxHOURGLASS_CURSOR
);
474 // Restore cursor to normal
475 WXDLLEXPORT
void wxEndBusyCursor();
477 // true if we're between the above two calls
478 WXDLLEXPORT
bool wxIsBusy();
480 // Convenience class so we can just create a wxBusyCursor object on the stack
481 class WXDLLEXPORT wxBusyCursor
484 wxBusyCursor(wxCursor
* cursor
= wxHOURGLASS_CURSOR
)
485 { wxBeginBusyCursor(cursor
); }
487 { wxEndBusyCursor(); }
489 // FIXME: These two methods are currently only implemented (and needed?)
490 // in wxGTK. BusyCursor handling should probably be moved to
491 // common code since the wxGTK and wxMSW implementations are very
492 // similar except for wxMSW using HCURSOR directly instead of
494 static const wxCursor
&GetStoredCursor();
495 static const wxCursor
GetBusyCursor();
499 // ----------------------------------------------------------------------------
500 // Reading and writing resources (eg WIN.INI, .Xdefaults)
501 // ----------------------------------------------------------------------------
504 WXDLLEXPORT
bool wxWriteResource(const wxString
& section
, const wxString
& entry
, const wxString
& value
, const wxString
& file
= wxEmptyString
);
505 WXDLLEXPORT
bool wxWriteResource(const wxString
& section
, const wxString
& entry
, float value
, const wxString
& file
= wxEmptyString
);
506 WXDLLEXPORT
bool wxWriteResource(const wxString
& section
, const wxString
& entry
, long value
, const wxString
& file
= wxEmptyString
);
507 WXDLLEXPORT
bool wxWriteResource(const wxString
& section
, const wxString
& entry
, int value
, const wxString
& file
= wxEmptyString
);
509 WXDLLEXPORT
bool wxGetResource(const wxString
& section
, const wxString
& entry
, wxChar
**value
, const wxString
& file
= wxEmptyString
);
510 WXDLLEXPORT
bool wxGetResource(const wxString
& section
, const wxString
& entry
, float *value
, const wxString
& file
= wxEmptyString
);
511 WXDLLEXPORT
bool wxGetResource(const wxString
& section
, const wxString
& entry
, long *value
, const wxString
& file
= wxEmptyString
);
512 WXDLLEXPORT
bool wxGetResource(const wxString
& section
, const wxString
& entry
, int *value
, const wxString
& file
= wxEmptyString
);
513 #endif // wxUSE_RESOURCES
515 void WXDLLEXPORT
wxGetMousePosition( int* x
, int* y
);
517 // MSW only: get user-defined resource from the .res file.
518 // Returns NULL or newly-allocated memory, so use delete[] to clean up.
520 extern WXDLLEXPORT
const wxChar
* wxUserResourceStr
;
521 WXDLLEXPORT wxChar
* wxLoadUserResource(const wxString
& resourceName
, const wxString
& resourceType
= wxUserResourceStr
);
524 // ----------------------------------------------------------------------------
525 // Display and colorss (X only)
526 // ----------------------------------------------------------------------------
529 void *wxGetDisplay();
533 WXDLLIMPEXP_CORE WXDisplay
*wxGetDisplay();
534 WXDLLIMPEXP_CORE
bool wxSetDisplay(const wxString
& display_name
);
535 WXDLLIMPEXP_CORE wxString
wxGetDisplayName();
540 #ifdef __VMS__ // Xlib.h for VMS is not (yet) compatible with C++
541 // The resulting warnings are switched off here
542 #pragma message disable nosimpint
544 // #include <X11/Xlib.h>
546 #pragma message enable nosimpint
553 // ----------------------------------------------------------------------------
554 // wxYield(): these functions are obsolete, please use wxApp methods instead!
555 // ----------------------------------------------------------------------------
557 // Yield to other apps/messages
558 WXDLLIMPEXP_BASE
bool wxYield();
560 // Like wxYield, but fails silently if the yield is recursive.
561 WXDLLIMPEXP_BASE
bool wxYieldIfNeeded();
563 // ----------------------------------------------------------------------------
564 // Error message functions used by wxWidgets (deprecated, use wxLog)
565 // ----------------------------------------------------------------------------