1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: Miscellaneous utilities
4 // Author: Julian Smart
8 // Copyright: (c) 1998 Julian Smart
9 // Licence: wxWindows license
10 /////////////////////////////////////////////////////////////////////////////
15 // ----------------------------------------------------------------------------
17 // ----------------------------------------------------------------------------
20 #pragma interface "utils.h"
23 #include "wx/object.h"
25 #include "wx/filefn.h"
27 // need this for wxGetDiskSpace() as we can't, unfortunately, forward declare
29 #include "wx/longlong.h"
38 // ----------------------------------------------------------------------------
39 // Forward declaration
40 // ----------------------------------------------------------------------------
42 class WXDLLEXPORT wxProcess
;
43 class WXDLLEXPORT wxFrame
;
44 class WXDLLEXPORT wxWindow
;
45 class WXDLLEXPORT wxWindowList
;
46 class WXDLLEXPORT wxPoint
;
48 // ----------------------------------------------------------------------------
50 // ----------------------------------------------------------------------------
52 #define wxMax(a,b) (((a) > (b)) ? (a) : (b))
53 #define wxMin(a,b) (((a) < (b)) ? (a) : (b))
55 // ----------------------------------------------------------------------------
56 // String functions (deprecated, use wxString)
57 // ----------------------------------------------------------------------------
59 // Useful buffer (FIXME VZ: To be removed!!!)
60 // Now only needed in Mac and MSW ports
61 #if !defined(__WXMOTIF__) && !defined(__WXGTK__) && !defined(__WXX11__) && !defined(__WXMGL__)
62 WXDLLEXPORT_DATA(extern wxChar
*) wxBuffer
;
65 // Make a copy of this string using 'new'
66 WXDLLEXPORT wxChar
* copystring(const wxChar
*s
);
68 // Matches string one within string two regardless of case
69 WXDLLEXPORT
bool StringMatch(const wxChar
*one
, const wxChar
*two
, bool subString
= TRUE
, bool exact
= FALSE
);
71 // A shorter way of using strcmp
72 #define wxStringEq(s1, s2) (s1 && s2 && (wxStrcmp(s1, s2) == 0))
74 // ----------------------------------------------------------------------------
75 // Miscellaneous functions
76 // ----------------------------------------------------------------------------
79 WXDLLEXPORT
void wxBell();
81 // Get OS description as a user-readable string
82 WXDLLEXPORT wxString
wxGetOsDescription();
85 WXDLLEXPORT
int wxGetOsVersion(int *majorVsn
= (int *) NULL
,
86 int *minorVsn
= (int *) NULL
);
88 // Return a string with the current date/time
89 WXDLLEXPORT wxString
wxNow();
91 // Return path where wxWindows is installed (mostly useful in Unices)
92 WXDLLEXPORT
const wxChar
*wxGetInstallPrefix();
93 // Return path to wxWin data (/usr/share/wx/%{version}) (Unices)
94 WXDLLEXPORT wxString
wxGetDataDir();
98 // Don't synthesize KeyUp events holding down a key and producing
99 // KeyDown events with autorepeat. On by default and always on
101 WXDLLEXPORT
bool wxSetDetectableAutoRepeat( bool flag
);
103 // ----------------------------------------------------------------------------
104 // Window ID management
105 // ----------------------------------------------------------------------------
107 // Generate a unique ID
108 WXDLLEXPORT
long wxNewId();
109 #if !defined(NewId) && defined(WXWIN_COMPATIBILITY)
110 #define NewId wxNewId
113 // Ensure subsequent IDs don't clash with this one
114 WXDLLEXPORT
void wxRegisterId(long id
);
115 #if !defined(RegisterId) && defined(WXWIN_COMPATIBILITY)
116 #define RegisterId wxRegisterId
119 // Return the current ID
120 WXDLLEXPORT
long wxGetCurrentId();
124 // ----------------------------------------------------------------------------
125 // Various conversions
126 // ----------------------------------------------------------------------------
128 WXDLLEXPORT_DATA(extern const wxChar
*) wxFloatToStringStr
;
129 WXDLLEXPORT_DATA(extern const wxChar
*) wxDoubleToStringStr
;
131 WXDLLEXPORT
void StringToFloat(const wxChar
*s
, float *number
);
132 WXDLLEXPORT wxChar
* FloatToString(float number
, const wxChar
*fmt
= wxFloatToStringStr
);
133 WXDLLEXPORT
void StringToDouble(const wxChar
*s
, double *number
);
134 WXDLLEXPORT wxChar
* DoubleToString(double number
, const wxChar
*fmt
= wxDoubleToStringStr
);
135 WXDLLEXPORT
void StringToInt(const wxChar
*s
, int *number
);
136 WXDLLEXPORT
void StringToLong(const wxChar
*s
, long *number
);
137 WXDLLEXPORT wxChar
* IntToString(int number
);
138 WXDLLEXPORT wxChar
* LongToString(long number
);
140 // Convert 2-digit hex number to decimal
141 WXDLLEXPORT
int wxHexToDec(const wxString
& buf
);
143 // Convert decimal integer to 2-character hex string
144 WXDLLEXPORT
void wxDecToHex(int dec
, wxChar
*buf
);
145 WXDLLEXPORT wxString
wxDecToHex(int dec
);
147 // ----------------------------------------------------------------------------
148 // Process management
149 // ----------------------------------------------------------------------------
151 // NB: for backwars compatibility reasons the values of wxEXEC_[A]SYNC *must*
152 // be 0 and 1, don't change!
156 wxEXEC_ASYNC
= 0, // execute the process asynchronously
157 wxEXEC_SYNC
= 1, // synchronously
158 wxEXEC_NOHIDE
= 2 // under Windows, don't hide the child even if it's
159 // IO is redirected (this is done by default)
162 // Execute another program.
164 // If flags contain wxEXEC_SYNC, return -1 on failure and the exit code of the
165 // process if everything was ok. Otherwise (i.e. if wxEXEC_ASYNC), return 0 on
166 // failure and the PID of the launched process if ok.
167 WXDLLEXPORT
long wxExecute(wxChar
**argv
, int flags
= wxEXEC_ASYNC
,
168 wxProcess
*process
= (wxProcess
*) NULL
);
169 WXDLLEXPORT
long wxExecute(const wxString
& command
, int flags
= wxEXEC_ASYNC
,
170 wxProcess
*process
= (wxProcess
*) NULL
);
172 // execute the command capturing its output into an array line by line, this is
173 // always synchronous
174 WXDLLEXPORT
long wxExecute(const wxString
& command
,
175 wxArrayString
& output
);
177 // also capture stderr (also synchronous)
178 WXDLLEXPORT
long wxExecute(const wxString
& command
,
179 wxArrayString
& output
,
180 wxArrayString
& error
);
184 wxSIGNONE
= 0, // verify if the process exists under Unix
191 wxSIGIOT
= wxSIGABRT
, // another name
202 // further signals are different in meaning between different Unix systems
207 wxKILL_OK
, // no error
208 wxKILL_BAD_SIGNAL
, // no such signal
209 wxKILL_ACCESS_DENIED
, // permission denied
210 wxKILL_NO_PROCESS
, // no such process
211 wxKILL_ERROR
// another, unspecified error
214 // send the given signal to the process (only NONE and KILL are supported under
215 // Windows, all others mean TERM), return 0 if ok and -1 on error
217 // return detailed error in rc if not NULL
218 WXDLLEXPORT
int wxKill(long pid
,
219 wxSignal sig
= wxSIGTERM
,
220 wxKillError
*rc
= NULL
);
222 // Execute a command in an interactive shell window (always synchronously)
223 // If no command then just the shell
224 WXDLLEXPORT
bool wxShell(const wxString
& command
= wxEmptyString
);
226 // As wxShell(), but must give a (non interactive) command and its output will
227 // be returned in output array
228 WXDLLEXPORT
bool wxShell(const wxString
& command
, wxArrayString
& output
);
230 // Sleep for nSecs seconds
231 WXDLLEXPORT
void wxSleep(int nSecs
);
233 // Sleep for a given amount of milliseconds
234 WXDLLEXPORT
void wxUsleep(unsigned long milliseconds
);
236 // Get free memory in bytes, or -1 if cannot determine amount (e.g. on UNIX)
237 WXDLLEXPORT
long wxGetFreeMemory();
239 // should wxApp::OnFatalException() be called?
240 WXDLLEXPORT
bool wxHandleFatalExceptions(bool doit
= TRUE
);
242 // ----------------------------------------------------------------------------
243 // Environment variables
244 // ----------------------------------------------------------------------------
246 // returns TRUE if variable exists (value may be NULL if you just want to check
248 WXDLLEXPORT
bool wxGetEnv(const wxString
& var
, wxString
*value
);
250 // set the env var name to the given value, return TRUE on success
251 WXDLLEXPORT
bool wxSetEnv(const wxString
& var
, const wxChar
*value
);
253 // remove the env var from environment
254 inline bool wxUnsetEnv(const wxString
& var
) { return wxSetEnv(var
, NULL
); }
256 // ----------------------------------------------------------------------------
257 // Network and username functions.
258 // ----------------------------------------------------------------------------
260 // NB: "char *" functions are deprecated, use wxString ones!
263 WXDLLEXPORT
bool wxGetEmailAddress(wxChar
*buf
, int maxSize
);
264 WXDLLEXPORT wxString
wxGetEmailAddress();
267 WXDLLEXPORT
bool wxGetHostName(wxChar
*buf
, int maxSize
);
268 WXDLLEXPORT wxString
wxGetHostName();
271 WXDLLEXPORT wxString
wxGetFullHostName();
272 WXDLLEXPORT
bool wxGetFullHostName(wxChar
*buf
, int maxSize
);
274 // Get user ID e.g. jacs (this is known as login name under Unix)
275 WXDLLEXPORT
bool wxGetUserId(wxChar
*buf
, int maxSize
);
276 WXDLLEXPORT wxString
wxGetUserId();
278 // Get user name e.g. Julian Smart
279 WXDLLEXPORT
bool wxGetUserName(wxChar
*buf
, int maxSize
);
280 WXDLLEXPORT wxString
wxGetUserName();
282 // Get current Home dir and copy to dest (returns pstr->c_str())
283 WXDLLEXPORT wxString
wxGetHomeDir();
284 WXDLLEXPORT
const wxChar
* wxGetHomeDir(wxString
*pstr
);
286 // Get the user's home dir (caller must copy --- volatile)
287 // returns NULL is no HOME dir is known
288 #if defined(__UNIX__) && wxUSE_UNICODE
289 WXDLLEXPORT
const wxMB2WXbuf
wxGetUserHome(const wxString
& user
= wxEmptyString
);
291 WXDLLEXPORT wxChar
* wxGetUserHome(const wxString
& user
= wxEmptyString
);
294 // get number of total/free bytes on the disk where path belongs
295 WXDLLEXPORT
bool wxGetDiskSpace(const wxString
& path
,
296 wxLongLong
*pTotal
= NULL
,
297 wxLongLong
*pFree
= NULL
);
299 #if wxUSE_GUI // GUI only things from now on
301 // ----------------------------------------------------------------------------
302 // Menu accelerators related things
303 // ----------------------------------------------------------------------------
305 WXDLLEXPORT wxChar
* wxStripMenuCodes(const wxChar
*in
, wxChar
*out
= (wxChar
*) NULL
);
306 WXDLLEXPORT wxString
wxStripMenuCodes(const wxString
& str
);
309 class WXDLLEXPORT wxAcceleratorEntry
;
310 WXDLLEXPORT wxAcceleratorEntry
*wxGetAccelFromString(const wxString
& label
);
311 #endif // wxUSE_ACCEL
313 // ----------------------------------------------------------------------------
315 // ----------------------------------------------------------------------------
317 // Find the window/widget with the given title or label.
318 // Pass a parent to begin the search from, or NULL to look through
320 WXDLLEXPORT wxWindow
* wxFindWindowByLabel(const wxString
& title
, wxWindow
*parent
= (wxWindow
*) NULL
);
322 // Find window by name, and if that fails, by label.
323 WXDLLEXPORT wxWindow
* wxFindWindowByName(const wxString
& name
, wxWindow
*parent
= (wxWindow
*) NULL
);
325 // Returns menu item id or -1 if none.
326 WXDLLEXPORT
int wxFindMenuItemId(wxFrame
*frame
, const wxString
& menuString
, const wxString
& itemString
);
328 // Find the wxWindow at the given point. wxGenericFindWindowAtPoint
329 // is always present but may be less reliable than a native version.
330 WXDLLEXPORT wxWindow
* wxGenericFindWindowAtPoint(const wxPoint
& pt
);
331 WXDLLEXPORT wxWindow
* wxFindWindowAtPoint(const wxPoint
& pt
);
333 // ----------------------------------------------------------------------------
334 // Message/event queue helpers
335 // ----------------------------------------------------------------------------
337 // Yield to other apps/messages
338 WXDLLEXPORT
bool wxYield();
340 // Like wxYield, but fails silently if the yield is recursive.
341 WXDLLEXPORT
bool wxYieldIfNeeded();
343 // Yield to other apps/messages and disable user input
344 WXDLLEXPORT
bool wxSafeYield(wxWindow
*win
= NULL
);
346 // Enable or disable input to all top level windows
347 WXDLLEXPORT
void wxEnableTopLevelWindows(bool enable
= TRUE
);
349 // Check whether this window wants to process messages, e.g. Stop button
350 // in long calculations.
351 WXDLLEXPORT
bool wxCheckForInterrupt(wxWindow
*wnd
);
353 // Consume all events until no more left
354 WXDLLEXPORT
void wxFlushEvents();
356 // a class which disables all windows (except, may be, thegiven one) in its
357 // ctor and enables them back in its dtor
358 class WXDLLEXPORT wxWindowDisabler
361 wxWindowDisabler(wxWindow
*winToSkip
= (wxWindow
*)NULL
);
365 wxWindowList
*m_winDisabled
;
368 // ----------------------------------------------------------------------------
370 // ----------------------------------------------------------------------------
372 // Set the cursor to the busy cursor for all windows
373 class WXDLLEXPORT wxCursor
;
374 WXDLLEXPORT_DATA(extern wxCursor
*) wxHOURGLASS_CURSOR
;
375 WXDLLEXPORT
void wxBeginBusyCursor(wxCursor
*cursor
= wxHOURGLASS_CURSOR
);
377 // Restore cursor to normal
378 WXDLLEXPORT
void wxEndBusyCursor();
380 // TRUE if we're between the above two calls
381 WXDLLEXPORT
bool wxIsBusy();
383 // Convenience class so we can just create a wxBusyCursor object on the stack
384 class WXDLLEXPORT wxBusyCursor
387 wxBusyCursor(wxCursor
* cursor
= wxHOURGLASS_CURSOR
)
388 { wxBeginBusyCursor(cursor
); }
390 { wxEndBusyCursor(); }
392 // FIXME: These two methods are currently only implemented (and needed?)
393 // in wxGTK. BusyCursor handling should probably be moved to
394 // common code since the wxGTK and wxMSW implementations are very
395 // similar except for wxMSW using HCURSOR directly instead of
397 static const wxCursor
&GetStoredCursor();
398 static const wxCursor
GetBusyCursor();
402 // ----------------------------------------------------------------------------
403 // Reading and writing resources (eg WIN.INI, .Xdefaults)
404 // ----------------------------------------------------------------------------
407 WXDLLEXPORT
bool wxWriteResource(const wxString
& section
, const wxString
& entry
, const wxString
& value
, const wxString
& file
= wxEmptyString
);
408 WXDLLEXPORT
bool wxWriteResource(const wxString
& section
, const wxString
& entry
, float value
, const wxString
& file
= wxEmptyString
);
409 WXDLLEXPORT
bool wxWriteResource(const wxString
& section
, const wxString
& entry
, long value
, const wxString
& file
= wxEmptyString
);
410 WXDLLEXPORT
bool wxWriteResource(const wxString
& section
, const wxString
& entry
, int value
, const wxString
& file
= wxEmptyString
);
412 WXDLLEXPORT
bool wxGetResource(const wxString
& section
, const wxString
& entry
, wxChar
**value
, const wxString
& file
= wxEmptyString
);
413 WXDLLEXPORT
bool wxGetResource(const wxString
& section
, const wxString
& entry
, float *value
, const wxString
& file
= wxEmptyString
);
414 WXDLLEXPORT
bool wxGetResource(const wxString
& section
, const wxString
& entry
, long *value
, const wxString
& file
= wxEmptyString
);
415 WXDLLEXPORT
bool wxGetResource(const wxString
& section
, const wxString
& entry
, int *value
, const wxString
& file
= wxEmptyString
);
416 #endif // wxUSE_RESOURCES
418 void WXDLLEXPORT
wxGetMousePosition( int* x
, int* y
);
420 // MSW only: get user-defined resource from the .res file.
421 // Returns NULL or newly-allocated memory, so use delete[] to clean up.
423 WXDLLEXPORT
extern const wxChar
* wxUserResourceStr
;
424 WXDLLEXPORT wxChar
* wxLoadUserResource(const wxString
& resourceName
, const wxString
& resourceType
= wxUserResourceStr
);
427 // ----------------------------------------------------------------------------
428 // Display and colorss (X only)
429 // ----------------------------------------------------------------------------
432 void *wxGetDisplay();
436 WXDisplay
*wxGetDisplay();
437 bool wxSetDisplay(const wxString
& display_name
);
438 wxString
wxGetDisplayName();
443 #ifdef __VMS__ // Xlib.h for VMS is not (yet) compatible with C++
444 // The resulting warnings are switched off here
445 #pragma message disable nosimpint
447 // #include <X11/Xlib.h>
449 #pragma message enable nosimpint
456 // ----------------------------------------------------------------------------
457 // Error message functions used by wxWindows (deprecated, use wxLog)
458 // ----------------------------------------------------------------------------
460 #if WXWIN_COMPATIBILITY_2_2
462 // Format a message on the standard error (UNIX) or the debugging
464 WXDLLEXPORT
void wxDebugMsg(const wxChar
*fmt
...);
466 // Non-fatal error (continues)
467 WXDLLEXPORT_DATA(extern const wxChar
*) wxInternalErrorStr
;
468 WXDLLEXPORT
void wxError(const wxString
& msg
, const wxString
& title
= wxInternalErrorStr
);
470 // Fatal error (exits)
471 WXDLLEXPORT_DATA(extern const wxChar
*) wxFatalErrorStr
;
472 WXDLLEXPORT
void wxFatalError(const wxString
& msg
, const wxString
& title
= wxFatalErrorStr
);
474 #endif // WXWIN_COMPATIBILITY_2_2