]> git.saurik.com Git - wxWidgets.git/blob - include/wx/utils.h
applying patch 1345435
[wxWidgets.git] / include / wx / utils.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/utils.h
3 // Purpose: Miscellaneous utilities
4 // Author: Julian Smart
5 // Modified by:
6 // Created: 29/01/98
7 // RCS-ID: $Id$
8 // Copyright: (c) 1998 Julian Smart
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
11
12 #ifndef _WX_UTILSH__
13 #define _WX_UTILSH__
14
15 // ----------------------------------------------------------------------------
16 // headers
17 // ----------------------------------------------------------------------------
18
19 #include "wx/object.h"
20 #include "wx/list.h"
21 #include "wx/filefn.h"
22
23 class WXDLLIMPEXP_BASE wxArrayString;
24
25 // need this for wxGetDiskSpace() as we can't, unfortunately, forward declare
26 // wxLongLong
27 #include "wx/longlong.h"
28
29 #ifdef __WATCOMC__
30 #include <direct.h>
31 #elif defined(__X__)
32 #include <dirent.h>
33 #include <unistd.h>
34 #endif
35
36 #include <stdio.h>
37
38 // ----------------------------------------------------------------------------
39 // Forward declaration
40 // ----------------------------------------------------------------------------
41
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;
47
48 // ----------------------------------------------------------------------------
49 // Macros
50 // ----------------------------------------------------------------------------
51
52 #define wxMax(a,b) (((a) > (b)) ? (a) : (b))
53 #define wxMin(a,b) (((a) < (b)) ? (a) : (b))
54
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
61 #else
62 // 64 bit UNIX has sizeof(long) = 64
63 // assume 32 bit platforms cannnot return more than 32bits of
64 #define wxMemorySize long
65 #endif
66
67 // ----------------------------------------------------------------------------
68 // String functions (deprecated, use wxString)
69 // ----------------------------------------------------------------------------
70
71 // Make a copy of this string using 'new'
72 #if WXWIN_COMPATIBILITY_2_4
73 wxDEPRECATED( WXDLLIMPEXP_BASE wxChar* copystring(const wxChar *s) );
74 #endif
75
76 // A shorter way of using strcmp
77 #define wxStringEq(s1, s2) (s1 && s2 && (wxStrcmp(s1, s2) == 0))
78
79 // ----------------------------------------------------------------------------
80 // Miscellaneous functions
81 // ----------------------------------------------------------------------------
82
83 // Sound the bell
84 #if !defined __EMX__ && \
85 (defined __WXMOTIF__ || defined __WXGTK__ || defined __WXX11__)
86 WXDLLIMPEXP_CORE void wxBell();
87 #else
88 WXDLLIMPEXP_BASE void wxBell();
89 #endif
90
91 // Get OS description as a user-readable string
92 WXDLLIMPEXP_BASE wxString wxGetOsDescription();
93
94 // Get OS version
95 WXDLLIMPEXP_BASE int wxGetOsVersion(int *majorVsn = (int *) NULL,
96 int *minorVsn = (int *) NULL);
97
98 // Return a string with the current date/time
99 WXDLLIMPEXP_BASE wxString wxNow();
100
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();
105
106
107 #if wxUSE_GUI
108
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);
113
114
115 // Don't synthesize KeyUp events holding down a key and producing
116 // KeyDown events with autorepeat. On by default and always on
117 // in wxMSW.
118 WXDLLEXPORT bool wxSetDetectableAutoRepeat( bool flag );
119
120 // ----------------------------------------------------------------------------
121 // Window ID management
122 // ----------------------------------------------------------------------------
123
124 // Generate a unique ID
125 WXDLLEXPORT long wxNewId();
126
127 // Ensure subsequent IDs don't clash with this one
128 WXDLLEXPORT void wxRegisterId(long id);
129
130 // Return the current ID
131 WXDLLEXPORT long wxGetCurrentId();
132
133 #endif // wxUSE_GUI
134
135 // ----------------------------------------------------------------------------
136 // Various conversions
137 // ----------------------------------------------------------------------------
138
139 // these functions are deprecated, use wxString methods instead!
140 #if WXWIN_COMPATIBILITY_2_4
141
142 extern WXDLLIMPEXP_DATA_BASE(const wxChar*) wxFloatToStringStr;
143 extern WXDLLIMPEXP_DATA_BASE(const wxChar*) wxDoubleToStringStr;
144
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) );
153
154 #endif // WXWIN_COMPATIBILITY_2_4
155
156 // Convert 2-digit hex number to decimal
157 WXDLLIMPEXP_BASE int wxHexToDec(const wxString& buf);
158
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);
162
163 // ----------------------------------------------------------------------------
164 // Process management
165 // ----------------------------------------------------------------------------
166
167 // NB: for backwards compatibility reasons the values of wxEXEC_[A]SYNC *must*
168 // be 0 and 1, don't change!
169
170 enum
171 {
172 // execute the process asynchronously
173 wxEXEC_ASYNC = 0,
174
175 // execute it synchronously, i.e. wait until it finishes
176 wxEXEC_SYNC = 1,
177
178 // under Windows, don't hide the child even if it's IO is redirected (this
179 // is done by default)
180 wxEXEC_NOHIDE = 2,
181
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,
185
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
189 wxEXEC_NODISABLE = 8
190 };
191
192 // Execute another program.
193 //
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);
201
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,
206 int flags = 0);
207
208 // also capture stderr (also synchronous)
209 WXDLLIMPEXP_BASE long wxExecute(const wxString& command,
210 wxArrayString& output,
211 wxArrayString& error,
212 int flags = 0);
213
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
220
221 enum wxSignal
222 {
223 wxSIGNONE = 0, // verify if the process exists under Unix
224 wxSIGHUP,
225 wxSIGINT,
226 wxSIGQUIT,
227 wxSIGILL,
228 wxSIGTRAP,
229 wxSIGABRT,
230 wxSIGIOT = wxSIGABRT, // another name
231 wxSIGEMT,
232 wxSIGFPE,
233 wxSIGKILL,
234 wxSIGBUS,
235 wxSIGSEGV,
236 wxSIGSYS,
237 wxSIGPIPE,
238 wxSIGALRM,
239 wxSIGTERM
240
241 // further signals are different in meaning between different Unix systems
242 };
243
244 enum wxKillError
245 {
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
251 };
252
253 enum wxKillFlags
254 {
255 wxKILL_NOCHILDREN = 0, // don't kill children
256 wxKILL_CHILDREN = 1 // kill children
257 };
258
259 enum wxShutdownFlags
260 {
261 wxSHUTDOWN_POWEROFF, // power off the computer
262 wxSHUTDOWN_REBOOT // shutdown and reboot
263 };
264
265 // Shutdown or reboot the PC
266 WXDLLIMPEXP_BASE bool wxShutdown(wxShutdownFlags wFlags);
267
268 enum wxPowerType
269 {
270 wxPOWER_SOCKET,
271 wxPOWER_BATTERY,
272 wxPOWER_UNKNOWN
273 };
274
275 WXDLLIMPEXP_BASE wxPowerType wxGetPowerType();
276
277 enum wxBatteryState
278 {
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
284 };
285
286 WXDLLIMPEXP_BASE wxBatteryState wxGetBatteryState();
287
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
290 //
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);
296
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);
300
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);
304
305 // Sleep for nSecs seconds
306 WXDLLIMPEXP_BASE void wxSleep(int nSecs);
307
308 // Sleep for a given amount of milliseconds
309 WXDLLIMPEXP_BASE void wxMilliSleep(unsigned long milliseconds);
310
311 // Sleep for a given amount of microseconds
312 WXDLLIMPEXP_BASE void wxMicroSleep(unsigned long microseconds);
313
314 // Sleep for a given amount of milliseconds (old, bad name), use wxMilliSleep
315 wxDEPRECATED( WXDLLIMPEXP_BASE void wxUsleep(unsigned long milliseconds) );
316
317 // Get the process id of the current process
318 WXDLLIMPEXP_BASE unsigned long wxGetProcessId();
319
320 // Get free memory in bytes, or -1 if cannot determine amount (e.g. on UNIX)
321 WXDLLIMPEXP_BASE wxMemorySize wxGetFreeMemory();
322
323 #if wxUSE_ON_FATAL_EXCEPTION
324
325 // should wxApp::OnFatalException() be called?
326 WXDLLIMPEXP_BASE bool wxHandleFatalExceptions(bool doit = true);
327
328 #endif // wxUSE_ON_FATAL_EXCEPTION
329
330 // flags for wxLaunchDefaultBrowser
331 enum
332 {
333 wxBROWSER_NEW_WINDOW = 1
334 };
335
336 // Launch url in the user's default internet browser
337 WXDLLIMPEXP_BASE bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0);
338
339 // ----------------------------------------------------------------------------
340 // Environment variables
341 // ----------------------------------------------------------------------------
342
343 // returns true if variable exists (value may be NULL if you just want to check
344 // for this)
345 WXDLLIMPEXP_BASE bool wxGetEnv(const wxString& var, wxString *value);
346
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);
349
350 // remove the env var from environment
351 inline bool wxUnsetEnv(const wxString& var) { return wxSetEnv(var, NULL); }
352
353 // ----------------------------------------------------------------------------
354 // Network and username functions.
355 // ----------------------------------------------------------------------------
356
357 // NB: "char *" functions are deprecated, use wxString ones!
358
359 // Get eMail address
360 WXDLLIMPEXP_BASE bool wxGetEmailAddress(wxChar *buf, int maxSize);
361 WXDLLIMPEXP_BASE wxString wxGetEmailAddress();
362
363 // Get hostname.
364 WXDLLIMPEXP_BASE bool wxGetHostName(wxChar *buf, int maxSize);
365 WXDLLIMPEXP_BASE wxString wxGetHostName();
366
367 // Get FQDN
368 WXDLLIMPEXP_BASE wxString wxGetFullHostName();
369 WXDLLIMPEXP_BASE bool wxGetFullHostName(wxChar *buf, int maxSize);
370
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();
374
375 // Get user name e.g. Julian Smart
376 WXDLLIMPEXP_BASE bool wxGetUserName(wxChar *buf, int maxSize);
377 WXDLLIMPEXP_BASE wxString wxGetUserName();
378
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);
382
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);
387 #else
388 WXDLLIMPEXP_BASE wxChar* wxGetUserHome(const wxString& user = wxEmptyString);
389 #endif
390
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);
395
396 #if wxUSE_GUI // GUI only things from now on
397
398 // ----------------------------------------------------------------------------
399 // Menu accelerators related things
400 // ----------------------------------------------------------------------------
401
402 WXDLLEXPORT wxChar* wxStripMenuCodes(const wxChar *in, wxChar *out = (wxChar *) NULL);
403 WXDLLEXPORT wxString wxStripMenuCodes(const wxString& str);
404
405 #if wxUSE_ACCEL
406 class WXDLLEXPORT wxAcceleratorEntry;
407 WXDLLEXPORT wxAcceleratorEntry *wxGetAccelFromString(const wxString& label);
408 #endif // wxUSE_ACCEL
409
410 // ----------------------------------------------------------------------------
411 // Window search
412 // ----------------------------------------------------------------------------
413
414 // Returns menu item id or wxNOT_FOUND if none.
415 WXDLLEXPORT int wxFindMenuItemId(wxFrame *frame, const wxString& menuString, const wxString& itemString);
416
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);
421
422 // NB: this function is obsolete, use wxWindow::FindWindowByLabel() instead
423 //
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
426 // all windows.
427 WXDLLEXPORT wxWindow* wxFindWindowByLabel(const wxString& title, wxWindow *parent = (wxWindow *) NULL);
428
429 // NB: this function is obsolete, use wxWindow::FindWindowByName() instead
430 //
431 // Find window by name, and if that fails, by label.
432 WXDLLEXPORT wxWindow* wxFindWindowByName(const wxString& name, wxWindow *parent = (wxWindow *) NULL);
433
434 // ----------------------------------------------------------------------------
435 // Message/event queue helpers
436 // ----------------------------------------------------------------------------
437
438 // Yield to other apps/messages and disable user input
439 WXDLLEXPORT bool wxSafeYield(wxWindow *win = NULL, bool onlyIfNeeded = false);
440
441 // Enable or disable input to all top level windows
442 WXDLLEXPORT void wxEnableTopLevelWindows(bool enable = true);
443
444 // Check whether this window wants to process messages, e.g. Stop button
445 // in long calculations.
446 WXDLLEXPORT bool wxCheckForInterrupt(wxWindow *wnd);
447
448 // Consume all events until no more left
449 WXDLLEXPORT void wxFlushEvents();
450
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
454 {
455 public:
456 wxWindowDisabler(wxWindow *winToSkip = (wxWindow *)NULL);
457 ~wxWindowDisabler();
458
459 private:
460 wxWindowList *m_winDisabled;
461
462 DECLARE_NO_COPY_CLASS(wxWindowDisabler)
463 };
464
465 // ----------------------------------------------------------------------------
466 // Cursors
467 // ----------------------------------------------------------------------------
468
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);
473
474 // Restore cursor to normal
475 WXDLLEXPORT void wxEndBusyCursor();
476
477 // true if we're between the above two calls
478 WXDLLEXPORT bool wxIsBusy();
479
480 // Convenience class so we can just create a wxBusyCursor object on the stack
481 class WXDLLEXPORT wxBusyCursor
482 {
483 public:
484 wxBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR)
485 { wxBeginBusyCursor(cursor); }
486 ~wxBusyCursor()
487 { wxEndBusyCursor(); }
488
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
493 // wxCursor.. -- RL.
494 static const wxCursor &GetStoredCursor();
495 static const wxCursor GetBusyCursor();
496 };
497
498
499 // ----------------------------------------------------------------------------
500 // Reading and writing resources (eg WIN.INI, .Xdefaults)
501 // ----------------------------------------------------------------------------
502
503 #if wxUSE_RESOURCES
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);
508
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
514
515 void WXDLLEXPORT wxGetMousePosition( int* x, int* y );
516
517 // MSW only: get user-defined resource from the .res file.
518 // Returns NULL or newly-allocated memory, so use delete[] to clean up.
519 #ifdef __WXMSW__
520 extern WXDLLEXPORT const wxChar* wxUserResourceStr;
521 WXDLLEXPORT wxChar* wxLoadUserResource(const wxString& resourceName, const wxString& resourceType = wxUserResourceStr);
522 #endif // MSW
523
524 // ----------------------------------------------------------------------------
525 // Display and colorss (X only)
526 // ----------------------------------------------------------------------------
527
528 #ifdef __WXGTK__
529 void *wxGetDisplay();
530 #endif
531
532 #ifdef __X__
533 WXDLLIMPEXP_CORE WXDisplay *wxGetDisplay();
534 WXDLLIMPEXP_CORE bool wxSetDisplay(const wxString& display_name);
535 WXDLLIMPEXP_CORE wxString wxGetDisplayName();
536 #endif // X or GTK+
537
538 #ifdef __X__
539
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
543 #endif
544 // #include <X11/Xlib.h>
545 #ifdef __VMS__
546 #pragma message enable nosimpint
547 #endif
548
549 #endif //__X__
550
551 #endif // wxUSE_GUI
552
553 // ----------------------------------------------------------------------------
554 // wxYield(): these functions are obsolete, please use wxApp methods instead!
555 // ----------------------------------------------------------------------------
556
557 // Yield to other apps/messages
558 WXDLLIMPEXP_BASE bool wxYield();
559
560 // Like wxYield, but fails silently if the yield is recursive.
561 WXDLLIMPEXP_BASE bool wxYieldIfNeeded();
562
563 // ----------------------------------------------------------------------------
564 // Error message functions used by wxWidgets (deprecated, use wxLog)
565 // ----------------------------------------------------------------------------
566
567 #endif
568 // _WX_UTILSH__