]> git.saurik.com Git - wxWidgets.git/blob - include/wx/utils.h
Added wxBitmap::UseAlpha() stub.
[wxWidgets.git] / include / wx / utils.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: 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 #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
26 // such files.
27 #pragma interface "utils.h"
28 #endif
29
30 #include "wx/object.h"
31 #include "wx/list.h"
32 #include "wx/filefn.h"
33
34 class WXDLLIMPEXP_BASE wxArrayString;
35
36 // need this for wxGetDiskSpace() as we can't, unfortunately, forward declare
37 // wxLongLong
38 #include "wx/longlong.h"
39
40 #ifdef __X__
41 #include <dirent.h>
42 #include <unistd.h>
43 #endif
44
45 #include <stdio.h>
46
47 // ----------------------------------------------------------------------------
48 // Forward declaration
49 // ----------------------------------------------------------------------------
50
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;
56
57 // ----------------------------------------------------------------------------
58 // Macros
59 // ----------------------------------------------------------------------------
60
61 #define wxMax(a,b) (((a) > (b)) ? (a) : (b))
62 #define wxMin(a,b) (((a) < (b)) ? (a) : (b))
63
64 // wxGetFreeMemory can return huge amount of memory on 64-bit platforms
65 // define wxMemorySize according to the type which best fits your platform
66 #if wxUSE_LONGLONG && defined(__WIN64__)
67 // 64 bit Windowses have sizeof(long) only 32 bit long
68 // we need to use wxLongLong to express memory sizes
69 #define wxMemorySize wxLongLong
70 #else
71 // 64 bit UNIX has sizeof(long) = 64
72 // assume 32 bit platforms cannnot return more than 32bits of
73 #define wxMemorySize long
74 #endif
75
76 // ----------------------------------------------------------------------------
77 // String functions (deprecated, use wxString)
78 // ----------------------------------------------------------------------------
79
80 // Make a copy of this string using 'new'
81 #if WXWIN_COMPATIBILITY_2_4
82 WXDLLIMPEXP_BASE wxChar* copystring(const wxChar *s);
83 #endif
84
85 // A shorter way of using strcmp
86 #define wxStringEq(s1, s2) (s1 && s2 && (wxStrcmp(s1, s2) == 0))
87
88 // ----------------------------------------------------------------------------
89 // Miscellaneous functions
90 // ----------------------------------------------------------------------------
91
92 // Sound the bell
93 WXDLLIMPEXP_BASE void wxBell();
94
95 // Get OS description as a user-readable string
96 WXDLLIMPEXP_BASE wxString wxGetOsDescription();
97
98 // Get OS version
99 WXDLLIMPEXP_BASE int wxGetOsVersion(int *majorVsn = (int *) NULL,
100 int *minorVsn = (int *) NULL);
101
102 // Return a string with the current date/time
103 WXDLLIMPEXP_BASE wxString wxNow();
104
105 // Return path where wxWidgets is installed (mostly useful in Unices)
106 WXDLLIMPEXP_BASE const wxChar *wxGetInstallPrefix();
107 // Return path to wxWin data (/usr/share/wx/%{version}) (Unices)
108 WXDLLIMPEXP_BASE wxString wxGetDataDir();
109
110
111 #if wxUSE_GUI
112
113 // Get the state of a key (true if pressed, false if not)
114 // This is generally most useful getting the state of
115 // the modifier or toggle keys.
116 WXDLLEXPORT bool wxGetKeyState(wxKeyCode key);
117
118
119 // Don't synthesize KeyUp events holding down a key and producing
120 // KeyDown events with autorepeat. On by default and always on
121 // in wxMSW.
122 WXDLLEXPORT bool wxSetDetectableAutoRepeat( bool flag );
123
124 // ----------------------------------------------------------------------------
125 // Window ID management
126 // ----------------------------------------------------------------------------
127
128 // Generate a unique ID
129 WXDLLEXPORT long wxNewId();
130
131 // Ensure subsequent IDs don't clash with this one
132 WXDLLEXPORT void wxRegisterId(long id);
133
134 // Return the current ID
135 WXDLLEXPORT long wxGetCurrentId();
136
137 #endif // wxUSE_GUI
138
139 // ----------------------------------------------------------------------------
140 // Various conversions
141 // ----------------------------------------------------------------------------
142
143 // these functions are deprecated, use wxString methods instead!
144 #if WXWIN_COMPATIBILITY_2_4
145
146 WXDLLIMPEXP_DATA_BASE(extern const wxChar*) wxFloatToStringStr;
147 WXDLLIMPEXP_DATA_BASE(extern const wxChar*) wxDoubleToStringStr;
148
149 WXDLLIMPEXP_BASE void StringToFloat(const wxChar *s, float *number);
150 WXDLLIMPEXP_BASE wxChar* FloatToString(float number, const wxChar *fmt = wxFloatToStringStr);
151 WXDLLIMPEXP_BASE void StringToDouble(const wxChar *s, double *number);
152 WXDLLIMPEXP_BASE wxChar* DoubleToString(double number, const wxChar *fmt = wxDoubleToStringStr);
153 WXDLLIMPEXP_BASE void StringToInt(const wxChar *s, int *number);
154 WXDLLIMPEXP_BASE void StringToLong(const wxChar *s, long *number);
155 WXDLLIMPEXP_BASE wxChar* IntToString(int number);
156 WXDLLIMPEXP_BASE wxChar* LongToString(long number);
157
158 #endif // WXWIN_COMPATIBILITY_2_4
159
160 // Convert 2-digit hex number to decimal
161 WXDLLIMPEXP_BASE int wxHexToDec(const wxString& buf);
162
163 // Convert decimal integer to 2-character hex string
164 WXDLLIMPEXP_BASE void wxDecToHex(int dec, wxChar *buf);
165 WXDLLIMPEXP_BASE wxString wxDecToHex(int dec);
166
167 // ----------------------------------------------------------------------------
168 // Process management
169 // ----------------------------------------------------------------------------
170
171 // NB: for backwards compatibility reasons the values of wxEXEC_[A]SYNC *must*
172 // be 0 and 1, don't change!
173
174 enum
175 {
176 // execute the process asynchronously
177 wxEXEC_ASYNC = 0,
178
179 // execute it synchronously, i.e. wait until it finishes
180 wxEXEC_SYNC = 1,
181
182 // under Windows, don't hide the child even if it's IO is redirected (this
183 // is done by default)
184 wxEXEC_NOHIDE = 2,
185
186 // under Unix, if the process is the group leader then passing wxKILL_CHILDREN to wxKill
187 // kills all children as well as pid
188 wxEXEC_MAKE_GROUP_LEADER = 4,
189
190 // by default synchronous execution disables all program windows to avoid
191 // that the user interacts with the program while the child process is
192 // running, you can use this flag to prevent this from happening
193 wxEXEC_NODISABLE = 8
194 };
195
196 // Execute another program.
197 //
198 // If flags contain wxEXEC_SYNC, return -1 on failure and the exit code of the
199 // process if everything was ok. Otherwise (i.e. if wxEXEC_ASYNC), return 0 on
200 // failure and the PID of the launched process if ok.
201 WXDLLIMPEXP_BASE long wxExecute(wxChar **argv, int flags = wxEXEC_ASYNC,
202 wxProcess *process = (wxProcess *) NULL);
203 WXDLLIMPEXP_BASE long wxExecute(const wxString& command, int flags = wxEXEC_ASYNC,
204 wxProcess *process = (wxProcess *) NULL);
205
206 // execute the command capturing its output into an array line by line, this is
207 // always synchronous
208 WXDLLIMPEXP_BASE long wxExecute(const wxString& command,
209 wxArrayString& output,
210 int flags = 0);
211
212 // also capture stderr (also synchronous)
213 WXDLLIMPEXP_BASE long wxExecute(const wxString& command,
214 wxArrayString& output,
215 wxArrayString& error,
216 int flags = 0);
217
218 enum wxSignal
219 {
220 wxSIGNONE = 0, // verify if the process exists under Unix
221 wxSIGHUP,
222 wxSIGINT,
223 wxSIGQUIT,
224 wxSIGILL,
225 wxSIGTRAP,
226 wxSIGABRT,
227 wxSIGIOT = wxSIGABRT, // another name
228 wxSIGEMT,
229 wxSIGFPE,
230 wxSIGKILL,
231 wxSIGBUS,
232 wxSIGSEGV,
233 wxSIGSYS,
234 wxSIGPIPE,
235 wxSIGALRM,
236 wxSIGTERM
237
238 // further signals are different in meaning between different Unix systems
239 };
240
241 enum wxKillError
242 {
243 wxKILL_OK, // no error
244 wxKILL_BAD_SIGNAL, // no such signal
245 wxKILL_ACCESS_DENIED, // permission denied
246 wxKILL_NO_PROCESS, // no such process
247 wxKILL_ERROR // another, unspecified error
248 };
249
250 enum wxKillFlags
251 {
252 wxKILL_NOCHILDREN = 0, // don't kill children
253 wxKILL_CHILDREN = 1 // kill children
254 };
255
256 enum wxShutdownFlags
257 {
258 wxSHUTDOWN_POWEROFF, // power off the computer
259 wxSHUTDOWN_REBOOT // shutdown and reboot
260 };
261
262 // Shutdown or reboot the PC
263 WXDLLIMPEXP_BASE bool wxShutdown(wxShutdownFlags wFlags);
264
265 // send the given signal to the process (only NONE and KILL are supported under
266 // Windows, all others mean TERM), return 0 if ok and -1 on error
267 //
268 // return detailed error in rc if not NULL
269 WXDLLIMPEXP_BASE int wxKill(long pid,
270 wxSignal sig = wxSIGTERM,
271 wxKillError *rc = NULL,
272 int flags = wxKILL_NOCHILDREN);
273
274 // Execute a command in an interactive shell window (always synchronously)
275 // If no command then just the shell
276 WXDLLIMPEXP_BASE bool wxShell(const wxString& command = wxEmptyString);
277
278 // As wxShell(), but must give a (non interactive) command and its output will
279 // be returned in output array
280 WXDLLIMPEXP_BASE bool wxShell(const wxString& command, wxArrayString& output);
281
282 // Sleep for nSecs seconds
283 WXDLLIMPEXP_BASE void wxSleep(int nSecs);
284
285 // Sleep for a given amount of milliseconds
286 WXDLLIMPEXP_BASE void wxMilliSleep(unsigned long milliseconds);
287
288 // Sleep for a given amount of microseconds
289 WXDLLIMPEXP_BASE void wxMicroSleep(unsigned long microseconds);
290
291 // Sleep for a given amount of milliseconds (old, bad name), use wxMilliSleep
292 wxDEPRECATED( WXDLLIMPEXP_BASE void wxUsleep(unsigned long milliseconds) );
293
294 // Get the process id of the current process
295 WXDLLIMPEXP_BASE unsigned long wxGetProcessId();
296
297 // Get free memory in bytes, or -1 if cannot determine amount (e.g. on UNIX)
298 WXDLLIMPEXP_BASE wxMemorySize wxGetFreeMemory();
299
300 // should wxApp::OnFatalException() be called?
301 WXDLLIMPEXP_BASE bool wxHandleFatalExceptions(bool doit = true);
302
303 // ----------------------------------------------------------------------------
304 // Environment variables
305 // ----------------------------------------------------------------------------
306
307 // returns true if variable exists (value may be NULL if you just want to check
308 // for this)
309 WXDLLIMPEXP_BASE bool wxGetEnv(const wxString& var, wxString *value);
310
311 // set the env var name to the given value, return true on success
312 WXDLLIMPEXP_BASE bool wxSetEnv(const wxString& var, const wxChar *value);
313
314 // remove the env var from environment
315 inline bool wxUnsetEnv(const wxString& var) { return wxSetEnv(var, NULL); }
316
317 // ----------------------------------------------------------------------------
318 // Network and username functions.
319 // ----------------------------------------------------------------------------
320
321 // NB: "char *" functions are deprecated, use wxString ones!
322
323 // Get eMail address
324 WXDLLIMPEXP_BASE bool wxGetEmailAddress(wxChar *buf, int maxSize);
325 WXDLLIMPEXP_BASE wxString wxGetEmailAddress();
326
327 // Get hostname.
328 WXDLLIMPEXP_BASE bool wxGetHostName(wxChar *buf, int maxSize);
329 WXDLLIMPEXP_BASE wxString wxGetHostName();
330
331 // Get FQDN
332 WXDLLIMPEXP_BASE wxString wxGetFullHostName();
333 WXDLLIMPEXP_BASE bool wxGetFullHostName(wxChar *buf, int maxSize);
334
335 // Get user ID e.g. jacs (this is known as login name under Unix)
336 WXDLLIMPEXP_BASE bool wxGetUserId(wxChar *buf, int maxSize);
337 WXDLLIMPEXP_BASE wxString wxGetUserId();
338
339 // Get user name e.g. Julian Smart
340 WXDLLIMPEXP_BASE bool wxGetUserName(wxChar *buf, int maxSize);
341 WXDLLIMPEXP_BASE wxString wxGetUserName();
342
343 // Get current Home dir and copy to dest (returns pstr->c_str())
344 WXDLLIMPEXP_BASE wxString wxGetHomeDir();
345 WXDLLIMPEXP_BASE const wxChar* wxGetHomeDir(wxString *pstr);
346
347 // Get the user's home dir (caller must copy --- volatile)
348 // returns NULL is no HOME dir is known
349 #if defined(__UNIX__) && wxUSE_UNICODE
350 WXDLLIMPEXP_BASE const wxMB2WXbuf wxGetUserHome(const wxString& user = wxEmptyString);
351 #else
352 WXDLLIMPEXP_BASE wxChar* wxGetUserHome(const wxString& user = wxEmptyString);
353 #endif
354
355 // get number of total/free bytes on the disk where path belongs
356 WXDLLIMPEXP_BASE bool wxGetDiskSpace(const wxString& path,
357 wxLongLong *pTotal = NULL,
358 wxLongLong *pFree = NULL);
359
360 #if wxUSE_GUI // GUI only things from now on
361
362 // ----------------------------------------------------------------------------
363 // Menu accelerators related things
364 // ----------------------------------------------------------------------------
365
366 WXDLLEXPORT wxChar* wxStripMenuCodes(const wxChar *in, wxChar *out = (wxChar *) NULL);
367 WXDLLEXPORT wxString wxStripMenuCodes(const wxString& str);
368
369 #if wxUSE_ACCEL
370 class WXDLLEXPORT wxAcceleratorEntry;
371 WXDLLEXPORT wxAcceleratorEntry *wxGetAccelFromString(const wxString& label);
372 #endif // wxUSE_ACCEL
373
374 // ----------------------------------------------------------------------------
375 // Window search
376 // ----------------------------------------------------------------------------
377
378 // Returns menu item id or wxNOT_FOUND if none.
379 WXDLLEXPORT int wxFindMenuItemId(wxFrame *frame, const wxString& menuString, const wxString& itemString);
380
381 // Find the wxWindow at the given point. wxGenericFindWindowAtPoint
382 // is always present but may be less reliable than a native version.
383 WXDLLEXPORT wxWindow* wxGenericFindWindowAtPoint(const wxPoint& pt);
384 WXDLLEXPORT wxWindow* wxFindWindowAtPoint(const wxPoint& pt);
385
386 // NB: this function is obsolete, use wxWindow::FindWindowByLabel() instead
387 //
388 // Find the window/widget with the given title or label.
389 // Pass a parent to begin the search from, or NULL to look through
390 // all windows.
391 WXDLLEXPORT wxWindow* wxFindWindowByLabel(const wxString& title, wxWindow *parent = (wxWindow *) NULL);
392
393 // NB: this function is obsolete, use wxWindow::FindWindowByName() instead
394 //
395 // Find window by name, and if that fails, by label.
396 WXDLLEXPORT wxWindow* wxFindWindowByName(const wxString& name, wxWindow *parent = (wxWindow *) NULL);
397
398 // ----------------------------------------------------------------------------
399 // Message/event queue helpers
400 // ----------------------------------------------------------------------------
401
402 // Yield to other apps/messages and disable user input
403 WXDLLEXPORT bool wxSafeYield(wxWindow *win = NULL, bool onlyIfNeeded = false);
404
405 // Enable or disable input to all top level windows
406 WXDLLEXPORT void wxEnableTopLevelWindows(bool enable = true);
407
408 // Check whether this window wants to process messages, e.g. Stop button
409 // in long calculations.
410 WXDLLEXPORT bool wxCheckForInterrupt(wxWindow *wnd);
411
412 // Consume all events until no more left
413 WXDLLEXPORT void wxFlushEvents();
414
415 // a class which disables all windows (except, may be, thegiven one) in its
416 // ctor and enables them back in its dtor
417 class WXDLLEXPORT wxWindowDisabler
418 {
419 public:
420 wxWindowDisabler(wxWindow *winToSkip = (wxWindow *)NULL);
421 ~wxWindowDisabler();
422
423 private:
424 wxWindowList *m_winDisabled;
425
426 DECLARE_NO_COPY_CLASS(wxWindowDisabler)
427 };
428
429 // ----------------------------------------------------------------------------
430 // Cursors
431 // ----------------------------------------------------------------------------
432
433 // Set the cursor to the busy cursor for all windows
434 class WXDLLEXPORT wxCursor;
435 WXDLLEXPORT_DATA(extern wxCursor*) wxHOURGLASS_CURSOR;
436 WXDLLEXPORT void wxBeginBusyCursor(wxCursor *cursor = wxHOURGLASS_CURSOR);
437
438 // Restore cursor to normal
439 WXDLLEXPORT void wxEndBusyCursor();
440
441 // true if we're between the above two calls
442 WXDLLEXPORT bool wxIsBusy();
443
444 // Convenience class so we can just create a wxBusyCursor object on the stack
445 class WXDLLEXPORT wxBusyCursor
446 {
447 public:
448 wxBusyCursor(wxCursor* cursor = wxHOURGLASS_CURSOR)
449 { wxBeginBusyCursor(cursor); }
450 ~wxBusyCursor()
451 { wxEndBusyCursor(); }
452
453 // FIXME: These two methods are currently only implemented (and needed?)
454 // in wxGTK. BusyCursor handling should probably be moved to
455 // common code since the wxGTK and wxMSW implementations are very
456 // similar except for wxMSW using HCURSOR directly instead of
457 // wxCursor.. -- RL.
458 static const wxCursor &GetStoredCursor();
459 static const wxCursor GetBusyCursor();
460 };
461
462
463 // ----------------------------------------------------------------------------
464 // Reading and writing resources (eg WIN.INI, .Xdefaults)
465 // ----------------------------------------------------------------------------
466
467 #if wxUSE_RESOURCES
468 WXDLLEXPORT bool wxWriteResource(const wxString& section, const wxString& entry, const wxString& value, const wxString& file = wxEmptyString);
469 WXDLLEXPORT bool wxWriteResource(const wxString& section, const wxString& entry, float value, const wxString& file = wxEmptyString);
470 WXDLLEXPORT bool wxWriteResource(const wxString& section, const wxString& entry, long value, const wxString& file = wxEmptyString);
471 WXDLLEXPORT bool wxWriteResource(const wxString& section, const wxString& entry, int value, const wxString& file = wxEmptyString);
472
473 WXDLLEXPORT bool wxGetResource(const wxString& section, const wxString& entry, wxChar **value, const wxString& file = wxEmptyString);
474 WXDLLEXPORT bool wxGetResource(const wxString& section, const wxString& entry, float *value, const wxString& file = wxEmptyString);
475 WXDLLEXPORT bool wxGetResource(const wxString& section, const wxString& entry, long *value, const wxString& file = wxEmptyString);
476 WXDLLEXPORT bool wxGetResource(const wxString& section, const wxString& entry, int *value, const wxString& file = wxEmptyString);
477 #endif // wxUSE_RESOURCES
478
479 void WXDLLEXPORT wxGetMousePosition( int* x, int* y );
480
481 // MSW only: get user-defined resource from the .res file.
482 // Returns NULL or newly-allocated memory, so use delete[] to clean up.
483 #ifdef __WXMSW__
484 WXDLLEXPORT extern const wxChar* wxUserResourceStr;
485 WXDLLEXPORT wxChar* wxLoadUserResource(const wxString& resourceName, const wxString& resourceType = wxUserResourceStr);
486 #endif // MSW
487
488 // ----------------------------------------------------------------------------
489 // Display and colorss (X only)
490 // ----------------------------------------------------------------------------
491
492 #ifdef __WXGTK__
493 void *wxGetDisplay();
494 #endif
495
496 #ifdef __X__
497 WXDisplay *wxGetDisplay();
498 bool wxSetDisplay(const wxString& display_name);
499 wxString wxGetDisplayName();
500 #endif // X or GTK+
501
502 #ifdef __X__
503
504 #ifdef __VMS__ // Xlib.h for VMS is not (yet) compatible with C++
505 // The resulting warnings are switched off here
506 #pragma message disable nosimpint
507 #endif
508 // #include <X11/Xlib.h>
509 #ifdef __VMS__
510 #pragma message enable nosimpint
511 #endif
512
513 #endif //__X__
514
515 #endif // wxUSE_GUI
516
517 // ----------------------------------------------------------------------------
518 // wxYield(): these functions are obsolete, please use wxApp methods instead!
519 // ----------------------------------------------------------------------------
520
521 // Yield to other apps/messages
522 WXDLLIMPEXP_BASE bool wxYield();
523
524 // Like wxYield, but fails silently if the yield is recursive.
525 WXDLLIMPEXP_BASE bool wxYieldIfNeeded();
526
527 // ----------------------------------------------------------------------------
528 // Error message functions used by wxWidgets (deprecated, use wxLog)
529 // ----------------------------------------------------------------------------
530
531 #if WXWIN_COMPATIBILITY_2_2
532
533 // Format a message on the standard error (UNIX) or the debugging
534 // stream (Windows)
535 WXDLLIMPEXP_BASE void wxDebugMsg(const wxChar *fmt ...) ATTRIBUTE_PRINTF_1;
536
537 // Non-fatal error (continues)
538 WXDLLIMPEXP_DATA_BASE(extern const wxChar*) wxInternalErrorStr;
539 WXDLLIMPEXP_BASE void wxError(const wxString& msg, const wxString& title = wxInternalErrorStr);
540
541 // Fatal error (exits)
542 WXDLLIMPEXP_DATA_BASE(extern const wxChar*) wxFatalErrorStr;
543 WXDLLIMPEXP_BASE void wxFatalError(const wxString& msg, const wxString& title = wxFatalErrorStr);
544
545 #endif // WXWIN_COMPATIBILITY_2_2
546
547 #endif
548 // _WX_UTILSH__