Coverage Report

Created: 2025-06-13 06:30

/src/wxwidgets/include/wx/utils.h
Line
Count
Source (jump to first uncovered line)
1
/////////////////////////////////////////////////////////////////////////////
2
// Name:        wx/utils.h
3
// Purpose:     Miscellaneous utilities
4
// Author:      Julian Smart
5
// Created:     29/01/98
6
// Copyright:   (c) 1998 Julian Smart
7
// Licence:     wxWindows licence
8
/////////////////////////////////////////////////////////////////////////////
9
10
#ifndef _WX_UTILS_H_
11
#define _WX_UTILS_H_
12
13
// ----------------------------------------------------------------------------
14
// headers
15
// ----------------------------------------------------------------------------
16
17
#include "wx/object.h"
18
#include "wx/filefn.h"
19
#include "wx/versioninfo.h"
20
#include "wx/meta/implicitconversion.h"
21
22
#if wxUSE_GUI
23
    #include "wx/busycursor.h"
24
    #include "wx/gdicmn.h"
25
    #include "wx/mousestate.h"
26
    #include "wx/vector.h"
27
#endif
28
29
class WXDLLIMPEXP_FWD_BASE wxArrayString;
30
class WXDLLIMPEXP_FWD_BASE wxArrayInt;
31
32
// need this for wxGetDiskSpace() as we can't, unfortunately, forward declare
33
// wxLongLong
34
#include "wx/longlong.h"
35
36
// needed for wxOperatingSystemId, wxLinuxDistributionInfo
37
#include "wx/platinfo.h"
38
39
// This is a hack, but this header used to include wx/hashmap.h which, in turn,
40
// included wx/wxcrt.h and it turns out quite some existing code relied on it
41
// by using the CRT wrapper functions declared there without explicitly
42
// including that header, so keep including it from here to let it continue to
43
// compile.
44
#include "wx/wxcrt.h"
45
46
#if defined(__X__)
47
    #include <dirent.h>
48
    #include <unistd.h>
49
#endif
50
51
#include <unordered_map>
52
53
// ----------------------------------------------------------------------------
54
// Forward declaration
55
// ----------------------------------------------------------------------------
56
57
class WXDLLIMPEXP_FWD_BASE wxProcess;
58
class WXDLLIMPEXP_FWD_CORE wxFrame;
59
class WXDLLIMPEXP_FWD_CORE wxWindow;
60
class WXDLLIMPEXP_FWD_CORE wxEventLoop;
61
62
// ----------------------------------------------------------------------------
63
// Arithmetic functions
64
// ----------------------------------------------------------------------------
65
66
template<typename T1, typename T2>
67
inline typename wxImplicitConversionType<T1,T2>::value
68
wxMax(T1 a, T2 b)
69
5.31k
{
70
5.31k
    typedef typename wxImplicitConversionType<T1,T2>::value ResultType;
71
72
    // Cast both operands to the same type before comparing them to avoid
73
    // warnings about signed/unsigned comparisons from some compilers:
74
5.31k
    return static_cast<ResultType>(a) > static_cast<ResultType>(b) ? a : b;
75
5.31k
}
wxImplicitConversionType<long, int>::value wxMax<long, int>(long, int)
Line
Count
Source
69
1.99k
{
70
1.99k
    typedef typename wxImplicitConversionType<T1,T2>::value ResultType;
71
72
    // Cast both operands to the same type before comparing them to avoid
73
    // warnings about signed/unsigned comparisons from some compilers:
74
1.99k
    return static_cast<ResultType>(a) > static_cast<ResultType>(b) ? a : b;
75
1.99k
}
wxImplicitConversionType<long, long>::value wxMax<long, long>(long, long)
Line
Count
Source
69
3.31k
{
70
3.31k
    typedef typename wxImplicitConversionType<T1,T2>::value ResultType;
71
72
    // Cast both operands to the same type before comparing them to avoid
73
    // warnings about signed/unsigned comparisons from some compilers:
74
3.31k
    return static_cast<ResultType>(a) > static_cast<ResultType>(b) ? a : b;
75
3.31k
}
76
77
template<typename T1, typename T2>
78
inline typename wxImplicitConversionType<T1,T2>::value
79
wxMin(T1 a, T2 b)
80
2.66k
{
81
2.66k
    typedef typename wxImplicitConversionType<T1,T2>::value ResultType;
82
83
2.66k
    return static_cast<ResultType>(a) < static_cast<ResultType>(b) ? a : b;
84
2.66k
}
Unexecuted instantiation: wxImplicitConversionType<unsigned long, unsigned long>::value wxMin<unsigned long, unsigned long>(unsigned long, unsigned long)
wxImplicitConversionType<unsigned short, int>::value wxMin<unsigned short, int>(unsigned short, int)
Line
Count
Source
80
2.66k
{
81
2.66k
    typedef typename wxImplicitConversionType<T1,T2>::value ResultType;
82
83
2.66k
    return static_cast<ResultType>(a) < static_cast<ResultType>(b) ? a : b;
84
2.66k
}
85
86
template<typename T1, typename T2, typename T3>
87
inline typename wxImplicitConversionType3<T1,T2,T3>::value
88
wxClip(T1 a, T2 b, T3 c)
89
{
90
    typedef typename wxImplicitConversionType3<T1,T2,T3>::value ResultType;
91
92
    if ( static_cast<ResultType>(a) < static_cast<ResultType>(b) )
93
        return b;
94
95
    if ( static_cast<ResultType>(a) > static_cast<ResultType>(c) )
96
        return c;
97
98
    return a;
99
}
100
101
// ----------------------------------------------------------------------------
102
// wxMemorySize
103
// ----------------------------------------------------------------------------
104
105
// wxGetFreeMemory can return huge amount of memory on 32-bit platforms as well
106
// so to always use long long for its result type on all platforms which
107
// support it
108
typedef wxLongLong wxMemorySize;
109
110
// ----------------------------------------------------------------------------
111
// Miscellaneous functions
112
// ----------------------------------------------------------------------------
113
114
// Sound the bell
115
WXDLLIMPEXP_CORE void wxBell();
116
117
#if wxUSE_MSGDLG
118
// Show wxWidgets information
119
WXDLLIMPEXP_CORE void wxInfoMessageBox(wxWindow* parent);
120
#endif // wxUSE_MSGDLG
121
122
WXDLLIMPEXP_BASE wxVersionInfo wxGetLibraryVersionInfo();
123
124
// Get OS description as a user-readable string
125
WXDLLIMPEXP_BASE wxString wxGetOsDescription();
126
127
// Get OS version
128
WXDLLIMPEXP_BASE wxOperatingSystemId wxGetOsVersion(int *verMaj = nullptr,
129
                                                    int *verMin = nullptr,
130
                                                    int *verMicro = nullptr);
131
132
// Check is OS version is at least the specified major and minor version
133
WXDLLIMPEXP_BASE bool wxCheckOsVersion(int majorVsn, int minorVsn = 0, int microVsn = 0);
134
135
// Get platform endianness
136
WXDLLIMPEXP_BASE bool wxIsPlatformLittleEndian();
137
138
// Get platform architecture bitness
139
WXDLLIMPEXP_BASE bool wxIsPlatform64Bit();
140
141
// Get machine CPU architecture
142
WXDLLIMPEXP_BASE wxString wxGetCpuArchitectureName();
143
144
// Get native machine CPU architecture
145
WXDLLIMPEXP_BASE wxString wxGetNativeCpuArchitectureName();
146
147
#ifdef __LINUX__
148
// Get linux-distro information
149
WXDLLIMPEXP_BASE wxLinuxDistributionInfo wxGetLinuxDistributionInfo();
150
#endif
151
152
// Return a string with the current date/time
153
WXDLLIMPEXP_BASE wxString wxNow();
154
155
// Return path where wxWidgets is installed (mostly useful in Unices)
156
WXDLLIMPEXP_BASE wxString wxGetInstallPrefix();
157
// Return path to wxWin data (/usr/share/wx/%{version}) (Unices)
158
WXDLLIMPEXP_BASE wxString wxGetDataDir();
159
160
#if wxUSE_GUI
161
162
// Get the state of a key (true if pressed, false if not)
163
// This is generally most useful getting the state of
164
// the modifier or toggle keys.
165
WXDLLIMPEXP_CORE bool wxGetKeyState(wxKeyCode key);
166
167
// Don't synthesize KeyUp events holding down a key and producing
168
// KeyDown events with autorepeat. On by default and always on
169
// in wxMSW.
170
WXDLLIMPEXP_CORE bool wxSetDetectableAutoRepeat( bool flag );
171
172
// Returns the current state of the mouse position, buttons and modifiers
173
WXDLLIMPEXP_CORE wxMouseState wxGetMouseState();
174
175
#endif // wxUSE_GUI
176
177
// ----------------------------------------------------------------------------
178
// wxPlatform
179
// ----------------------------------------------------------------------------
180
181
/*
182
 * Class to make it easier to specify platform-dependent values
183
 *
184
 * Examples:
185
 *  long val = wxPlatform::If(wxMac, 1).ElseIf(wxGTK, 2).ElseIf(stPDA, 5).Else(3);
186
 *  wxString strVal = wxPlatform::If(wxMac, wxT("Mac")).ElseIf(wxMSW, wxT("MSW")).Else(wxT("Other"));
187
 *
188
 * A custom platform symbol:
189
 *
190
 *  #define stPDA 100
191
 *  #ifdef __WXMSW__
192
 *      wxPlatform::AddPlatform(stPDA);
193
 *  #endif
194
 *
195
 *  long windowStyle = wxCAPTION | (long) wxPlatform::IfNot(stPDA, wxRESIZE_BORDER);
196
 *
197
 */
198
199
class WXDLLIMPEXP_BASE wxPlatform
200
{
201
public:
202
0
    wxPlatform() { Init(); }
203
0
    wxPlatform(const wxPlatform& platform) { Copy(platform); }
204
0
    void operator = (const wxPlatform& platform) { if (&platform != this) Copy(platform); }
205
    void Copy(const wxPlatform& platform);
206
207
    // Specify an optional default value
208
0
    wxPlatform(int defValue) { Init(); m_longValue = (long)defValue; }
209
0
    wxPlatform(long defValue) { Init(); m_longValue = defValue; }
210
0
    wxPlatform(const wxString& defValue) { Init(); m_stringValue = defValue; }
211
0
    wxPlatform(double defValue) { Init(); m_doubleValue = defValue; }
212
213
    static wxPlatform If(int platform, long value);
214
    static wxPlatform IfNot(int platform, long value);
215
    wxPlatform& ElseIf(int platform, long value);
216
    wxPlatform& ElseIfNot(int platform, long value);
217
    wxPlatform& Else(long value);
218
219
0
    static wxPlatform If(int platform, int value) { return If(platform, (long)value); }
220
0
    static wxPlatform IfNot(int platform, int value) { return IfNot(platform, (long)value); }
221
0
    wxPlatform& ElseIf(int platform, int value) { return ElseIf(platform, (long) value); }
222
0
    wxPlatform& ElseIfNot(int platform, int value) { return ElseIfNot(platform, (long) value); }
223
0
    wxPlatform& Else(int value) { return Else((long) value); }
224
225
    static wxPlatform If(int platform, double value);
226
    static wxPlatform IfNot(int platform, double value);
227
    wxPlatform& ElseIf(int platform, double value);
228
    wxPlatform& ElseIfNot(int platform, double value);
229
    wxPlatform& Else(double value);
230
231
    static wxPlatform If(int platform, const wxString& value);
232
    static wxPlatform IfNot(int platform, const wxString& value);
233
    wxPlatform& ElseIf(int platform, const wxString& value);
234
    wxPlatform& ElseIfNot(int platform, const wxString& value);
235
    wxPlatform& Else(const wxString& value);
236
237
0
    long GetInteger() const { return m_longValue; }
238
0
    const wxString& GetString() const { return m_stringValue; }
239
0
    double GetDouble() const { return m_doubleValue; }
240
241
0
    operator int() const { return (int) GetInteger(); }
242
0
    operator long() const { return GetInteger(); }
243
0
    operator double() const { return GetDouble(); }
244
0
    operator const wxString&() const { return GetString(); }
245
246
    static void AddPlatform(int platform);
247
    static bool Is(int platform);
248
    static void ClearPlatforms();
249
250
private:
251
252
0
    void Init() { m_longValue = 0; m_doubleValue = 0.0; }
253
254
    long                m_longValue;
255
    double              m_doubleValue;
256
    wxString            m_stringValue;
257
    static wxArrayInt*  sm_customPlatforms;
258
};
259
260
/// Function for testing current platform
261
0
inline bool wxPlatformIs(int platform) { return wxPlatform::Is(platform); }
262
263
// ----------------------------------------------------------------------------
264
// Window ID management
265
// ----------------------------------------------------------------------------
266
267
// Ensure subsequent IDs don't clash with this one
268
WXDLLIMPEXP_BASE void wxRegisterId(wxWindowID id);
269
270
// Return the current ID
271
WXDLLIMPEXP_BASE wxWindowID wxGetCurrentId();
272
273
// Generate a unique ID
274
WXDLLIMPEXP_BASE wxWindowID wxNewId();
275
276
// ----------------------------------------------------------------------------
277
// Various conversions
278
// ----------------------------------------------------------------------------
279
280
// Convert 2-digit hex number to decimal
281
WXDLLIMPEXP_BASE int wxHexToDec(const wxString& buf);
282
283
// Convert 2-digit hex number to decimal
284
inline int wxHexToDec(const char* buf)
285
0
{
286
0
    int firstDigit, secondDigit;
287
288
0
    if (buf[0] >= 'A')
289
0
        firstDigit = buf[0] - 'A' + 10;
290
0
    else if (buf[0] >= '0')
291
0
        firstDigit = buf[0] - '0';
292
0
    else
293
0
        firstDigit = -1;
294
295
0
    wxCHECK_MSG( firstDigit >= 0 && firstDigit <= 15, -1, wxS("Invalid argument") );
296
297
0
    if (buf[1] >= 'A')
298
0
        secondDigit = buf[1] - 'A' + 10;
299
0
    else if (buf[1] >= '0')
300
0
        secondDigit = buf[1] - '0';
301
0
    else
302
0
        secondDigit = -1;
303
304
0
    wxCHECK_MSG( secondDigit >= 0 && secondDigit <= 15, -1, wxS("Invalid argument") );
305
306
0
    return firstDigit * 16 + secondDigit;
307
0
}
308
309
310
// Convert decimal integer to 2-character hex string
311
WXDLLIMPEXP_BASE void wxDecToHex(unsigned char dec, wxChar *buf);
312
WXDLLIMPEXP_BASE void wxDecToHex(unsigned char dec, char* ch1, char* ch2);
313
WXDLLIMPEXP_BASE wxString wxDecToHex(unsigned char dec);
314
315
// ----------------------------------------------------------------------------
316
// Security
317
// ----------------------------------------------------------------------------
318
319
WXDLLIMPEXP_BASE void wxSecureZeroMemory(void *p, size_t n);
320
321
// ----------------------------------------------------------------------------
322
// Process management
323
// ----------------------------------------------------------------------------
324
325
// NB: for backwards compatibility reasons the values of wxEXEC_[A]SYNC *must*
326
//     be 0 and 1, don't change!
327
328
enum
329
{
330
    // execute the process asynchronously
331
    wxEXEC_ASYNC    = 0,
332
333
    // execute it synchronously, i.e. wait until it finishes
334
    wxEXEC_SYNC     = 1,
335
336
    // under Windows, don't hide the child even if it's IO is redirected (this
337
    // is done by default)
338
    wxEXEC_SHOW_CONSOLE   = 2,
339
340
    // deprecated synonym for wxEXEC_SHOW_CONSOLE, use the new name as it's
341
    // more clear
342
    wxEXEC_NOHIDE = wxEXEC_SHOW_CONSOLE,
343
344
    // under Unix, if the process is the group leader then passing wxKILL_CHILDREN to wxKill
345
    // kills all children as well as pid
346
    // under Windows (NT family only), sets the CREATE_NEW_PROCESS_GROUP flag,
347
    // which allows to target Ctrl-Break signal to the spawned process.
348
    // applies to console processes only.
349
    wxEXEC_MAKE_GROUP_LEADER = 4,
350
351
    // by default synchronous execution disables all program windows to avoid
352
    // that the user interacts with the program while the child process is
353
    // running, you can use this flag to prevent this from happening
354
    wxEXEC_NODISABLE = 8,
355
356
    // by default, the event loop is run while waiting for synchronous execution
357
    // to complete and this flag can be used to simply block the main process
358
    // until the child process finishes
359
    wxEXEC_NOEVENTS = 16,
360
361
    // under Windows, hide the console of the child process if it has one, even
362
    // if its IO is not redirected
363
    wxEXEC_HIDE_CONSOLE = 32,
364
365
    // convenient synonym for flags given system()-like behaviour
366
    wxEXEC_BLOCK = wxEXEC_SYNC | wxEXEC_NOEVENTS
367
};
368
369
// Map storing environment variables.
370
using wxEnvVariableHashMap = std::unordered_map<wxString, wxString>;
371
372
// Used to pass additional parameters for child process to wxExecute(). Could
373
// be extended with other fields later.
374
struct wxExecuteEnv
375
{
376
    wxString cwd;               // If empty, CWD is not changed.
377
    wxEnvVariableHashMap env;   // If empty, environment is unchanged.
378
};
379
380
// Execute another program.
381
//
382
// If flags contain wxEXEC_SYNC, return -1 on failure and the exit code of the
383
// process if everything was ok. Otherwise (i.e. if wxEXEC_ASYNC), return 0 on
384
// failure and the PID of the launched process if ok.
385
WXDLLIMPEXP_BASE long wxExecute(const wxString& command,
386
                                int flags = wxEXEC_ASYNC,
387
                                wxProcess *process = nullptr,
388
                                const wxExecuteEnv *env = nullptr);
389
WXDLLIMPEXP_BASE long wxExecute(const char* const* argv,
390
                                int flags = wxEXEC_ASYNC,
391
                                wxProcess *process = nullptr,
392
                                const wxExecuteEnv *env = nullptr);
393
WXDLLIMPEXP_BASE long wxExecute(const wchar_t* const* argv,
394
                                int flags = wxEXEC_ASYNC,
395
                                wxProcess *process = nullptr,
396
                                const wxExecuteEnv *env = nullptr);
397
398
// execute the command capturing its output into an array line by line, this is
399
// always synchronous
400
WXDLLIMPEXP_BASE long wxExecute(const wxString& command,
401
                                wxArrayString& output,
402
                                int flags = 0,
403
                                const wxExecuteEnv *env = nullptr);
404
405
// also capture stderr (also synchronous)
406
WXDLLIMPEXP_BASE long wxExecute(const wxString& command,
407
                                wxArrayString& output,
408
                                wxArrayString& error,
409
                                int flags = 0,
410
                                const wxExecuteEnv *env = nullptr);
411
412
#if defined(__WINDOWS__) && wxUSE_IPC
413
// ask a DDE server to execute the DDE request with given parameters
414
WXDLLIMPEXP_BASE bool wxExecuteDDE(const wxString& ddeServer,
415
                                   const wxString& ddeTopic,
416
                                   const wxString& ddeCommand);
417
#endif // __WINDOWS__ && wxUSE_IPC
418
419
enum wxSignal
420
{
421
    wxSIGNONE = 0,  // verify if the process exists under Unix
422
    wxSIGHUP,
423
    wxSIGINT,
424
    wxSIGQUIT,
425
    wxSIGILL,
426
    wxSIGTRAP,
427
    wxSIGABRT,
428
    wxSIGIOT = wxSIGABRT,   // another name
429
    wxSIGEMT,
430
    wxSIGFPE,
431
    wxSIGKILL,
432
    wxSIGBUS,
433
    wxSIGSEGV,
434
    wxSIGSYS,
435
    wxSIGPIPE,
436
    wxSIGALRM,
437
    wxSIGTERM
438
439
    // further signals are different in meaning between different Unix systems
440
};
441
442
enum wxKillError
443
{
444
    wxKILL_OK,              // no error
445
    wxKILL_BAD_SIGNAL,      // no such signal
446
    wxKILL_ACCESS_DENIED,   // permission denied
447
    wxKILL_NO_PROCESS,      // no such process
448
    wxKILL_ERROR            // another, unspecified error
449
};
450
451
enum wxKillFlags
452
{
453
    wxKILL_NOCHILDREN = 0,  // don't kill children
454
    wxKILL_CHILDREN = 1     // kill children
455
};
456
457
enum wxShutdownFlags
458
{
459
    wxSHUTDOWN_FORCE    = 1,// can be combined with other flags (MSW-only)
460
    wxSHUTDOWN_POWEROFF = 2,// power off the computer
461
    wxSHUTDOWN_REBOOT   = 4,// shutdown and reboot
462
    wxSHUTDOWN_LOGOFF   = 8 // close session (currently MSW-only)
463
};
464
465
// Shutdown or reboot the PC
466
WXDLLIMPEXP_BASE bool wxShutdown(int flags = wxSHUTDOWN_POWEROFF);
467
468
// send the given signal to the process (only NONE and KILL are supported under
469
// Windows, all others mean TERM), return 0 if ok and -1 on error
470
//
471
// return detailed error in rc is not null
472
WXDLLIMPEXP_BASE int wxKill(long pid,
473
                       wxSignal sig = wxSIGTERM,
474
                       wxKillError *rc = nullptr,
475
                       int flags = wxKILL_NOCHILDREN);
476
477
// Execute a command in an interactive shell window (always synchronously)
478
// If no command then just the shell
479
WXDLLIMPEXP_BASE bool wxShell(const wxString& command = wxEmptyString);
480
481
// As wxShell(), but must give a (non interactive) command and its output will
482
// be returned in output array
483
WXDLLIMPEXP_BASE bool wxShell(const wxString& command, wxArrayString& output);
484
485
// Sleep for nSecs seconds
486
WXDLLIMPEXP_BASE void wxSleep(int nSecs);
487
488
// Sleep for a given amount of milliseconds
489
WXDLLIMPEXP_BASE void wxMilliSleep(unsigned long milliseconds);
490
491
// Sleep for a given amount of microseconds
492
WXDLLIMPEXP_BASE void wxMicroSleep(unsigned long microseconds);
493
494
// Get the process id of the current process
495
WXDLLIMPEXP_BASE unsigned long wxGetProcessId();
496
497
// Get free memory in bytes, or -1 if cannot determine amount (e.g. on UNIX)
498
WXDLLIMPEXP_BASE wxMemorySize wxGetFreeMemory();
499
500
#if wxUSE_ON_FATAL_EXCEPTION
501
502
// should wxApp::OnFatalException() be called?
503
WXDLLIMPEXP_BASE bool wxHandleFatalExceptions(bool doit = true);
504
505
#endif // wxUSE_ON_FATAL_EXCEPTION
506
507
// ----------------------------------------------------------------------------
508
// Environment variables
509
// ----------------------------------------------------------------------------
510
511
// returns true if variable exists (value may be null if you just want to check
512
// for this)
513
WXDLLIMPEXP_BASE bool wxGetEnv(const wxString& var, wxString *value);
514
515
// set the env var name to the given value, return true on success
516
WXDLLIMPEXP_BASE bool wxSetEnv(const wxString& var, const wxString& value);
517
518
// remove the env var from environment
519
WXDLLIMPEXP_BASE bool wxUnsetEnv(const wxString& var);
520
521
// Retrieve the complete environment by filling specified map.
522
// Returns true on success or false if an error occurred.
523
WXDLLIMPEXP_BASE bool wxGetEnvMap(wxEnvVariableHashMap *map);
524
525
// ----------------------------------------------------------------------------
526
// Network and username functions.
527
// ----------------------------------------------------------------------------
528
529
// NB: "char *" functions are deprecated, use wxString ones!
530
531
// Get eMail address
532
WXDLLIMPEXP_BASE bool wxGetEmailAddress(wxChar *buf, int maxSize);
533
WXDLLIMPEXP_BASE wxString wxGetEmailAddress();
534
535
// Get hostname.
536
WXDLLIMPEXP_BASE bool wxGetHostName(wxChar *buf, int maxSize);
537
WXDLLIMPEXP_BASE wxString wxGetHostName();
538
539
// Get FQDN
540
WXDLLIMPEXP_BASE wxString wxGetFullHostName();
541
WXDLLIMPEXP_BASE bool wxGetFullHostName(wxChar *buf, int maxSize);
542
543
// Get user ID e.g. jacs (this is known as login name under Unix)
544
WXDLLIMPEXP_BASE bool wxGetUserId(wxChar *buf, int maxSize);
545
WXDLLIMPEXP_BASE wxString wxGetUserId();
546
547
// Get user name e.g. Julian Smart
548
WXDLLIMPEXP_BASE bool wxGetUserName(wxChar *buf, int maxSize);
549
WXDLLIMPEXP_BASE wxString wxGetUserName();
550
551
// Get current Home dir and copy to dest (returns pstr->c_str())
552
WXDLLIMPEXP_BASE wxString wxGetHomeDir();
553
WXDLLIMPEXP_BASE const wxChar* wxGetHomeDir(wxString *pstr);
554
555
// Get the user's (by default use the current user name) home dir,
556
// return empty string on error
557
WXDLLIMPEXP_BASE wxString wxGetUserHome(const wxString& user = wxEmptyString);
558
559
560
typedef wxLongLong wxDiskspaceSize_t;
561
562
// get number of total/free bytes on the disk where path belongs
563
WXDLLIMPEXP_BASE bool wxGetDiskSpace(const wxString& path,
564
                                     wxDiskspaceSize_t *pTotal = nullptr,
565
                                     wxDiskspaceSize_t *pFree = nullptr);
566
567
568
569
typedef int (*wxSortCallback)(const void* pItem1,
570
                              const void* pItem2,
571
                              const void* user_data);
572
573
574
#if WXWIN_COMPATIBILITY_3_2
575
wxDEPRECATED_MSG("Use std::sort instead")
576
WXDLLIMPEXP_BASE void wxQsort(void* pbase, size_t total_elems,
577
                              size_t size, wxSortCallback cmp,
578
                              const void* user_data);
579
#endif // WXWIN_COMPATIBILITY_3_2
580
581
#if wxUSE_GUI // GUI only things from now on
582
583
// ----------------------------------------------------------------------------
584
// Launch default browser
585
// ----------------------------------------------------------------------------
586
587
// flags for wxLaunchDefaultBrowser
588
enum
589
{
590
    wxBROWSER_NEW_WINDOW   = 0x01,
591
    wxBROWSER_NOBUSYCURSOR = 0x02
592
};
593
594
// Launch url in the user's default internet browser
595
WXDLLIMPEXP_CORE bool wxLaunchDefaultBrowser(const wxString& url, int flags = 0);
596
597
// Launch document in the user's default application
598
WXDLLIMPEXP_CORE bool wxLaunchDefaultApplication(const wxString& path, int flags = 0);
599
600
// ----------------------------------------------------------------------------
601
// Menu accelerators related things
602
// ----------------------------------------------------------------------------
603
604
// flags for wxStripMenuCodes
605
enum
606
{
607
    // strip '&' characters
608
    wxStrip_Mnemonics = 1,
609
610
    // strip everything after '\t'
611
    wxStrip_Accel = 2,
612
613
    // strip mnemonics of the form "(&X)" appended to the string (used in CJK
614
    // translations)
615
    wxStrip_CJKMnemonics = 4,
616
617
    // strip everything (this doesn't include wxStrip_CJKMnemonics for
618
    // compatibility)
619
    wxStrip_All = wxStrip_Mnemonics | wxStrip_Accel,
620
621
    // strip everything including CJK mnemonics, suitable for menu items labels
622
    // only (despite its name, wxStripMenuCodes() is currently used for control
623
    // labels too)
624
    wxStrip_Menu = wxStrip_All | wxStrip_CJKMnemonics
625
};
626
627
// strip mnemonics and/or accelerators from the label
628
WXDLLIMPEXP_CORE wxString
629
wxStripMenuCodes(const wxString& str, int flags = wxStrip_All);
630
631
// ----------------------------------------------------------------------------
632
// Window search
633
// ----------------------------------------------------------------------------
634
635
// Returns menu item id or wxNOT_FOUND if none.
636
WXDLLIMPEXP_CORE int wxFindMenuItemId(wxFrame *frame, const wxString& menuString, const wxString& itemString);
637
638
// Find the wxWindow at the given point. wxGenericFindWindowAtPoint
639
// is always present but may be less reliable than a native version.
640
WXDLLIMPEXP_CORE wxWindow* wxGenericFindWindowAtPoint(const wxPoint& pt);
641
WXDLLIMPEXP_CORE wxWindow* wxFindWindowAtPoint(const wxPoint& pt);
642
643
// NB: this function is obsolete, use wxWindow::FindWindowByLabel() instead
644
//
645
// Find the window/widget with the given title or label.
646
// Pass a parent to begin the search from, or nullptr to look through
647
// all windows.
648
WXDLLIMPEXP_CORE wxWindow* wxFindWindowByLabel(const wxString& title, wxWindow *parent = nullptr);
649
650
// NB: this function is obsolete, use wxWindow::FindWindowByName() instead
651
//
652
// Find window by name, and if that fails, by label.
653
WXDLLIMPEXP_CORE wxWindow* wxFindWindowByName(const wxString& name, wxWindow *parent = nullptr);
654
655
// ----------------------------------------------------------------------------
656
// Message/event queue helpers
657
// ----------------------------------------------------------------------------
658
659
// Yield to other apps/messages and disable user input
660
WXDLLIMPEXP_CORE bool wxSafeYield(wxWindow *win = nullptr, bool onlyIfNeeded = false);
661
662
// Enable or disable input to all top level windows
663
WXDLLIMPEXP_CORE void wxEnableTopLevelWindows(bool enable = true);
664
665
// Check whether this window wants to process messages, e.g. Stop button
666
// in long calculations.
667
WXDLLIMPEXP_CORE bool wxCheckForInterrupt(wxWindow *wnd);
668
669
// Consume all events until no more left
670
WXDLLIMPEXP_CORE void wxFlushEvents();
671
672
// a class which disables all windows (except, may be, the given one) in its
673
// ctor and enables them back in its dtor
674
class WXDLLIMPEXP_CORE wxWindowDisabler
675
{
676
public:
677
    // this ctor conditionally disables all windows: if the argument is false,
678
    // it doesn't do anything
679
    explicit wxWindowDisabler(bool disable = true);
680
681
    // ctor disables all windows except the given one(s)
682
    explicit wxWindowDisabler(wxWindow *winToSkip, wxWindow *winToSkip2 = nullptr);
683
684
    // dtor enables back all windows disabled by the ctor
685
    ~wxWindowDisabler();
686
687
private:
688
    // disable all windows not in m_windowsToSkip
689
    void DoDisable();
690
691
#if defined(__WXOSX__) && wxOSX_USE_COCOA
692
    void AfterDisable(wxWindow* winToSkip);
693
    void BeforeEnable();
694
695
    wxEventLoop* m_modalEventLoop = nullptr;
696
#endif
697
    wxVector<wxWindow*> m_windowsToSkip;
698
    bool m_disabled;
699
700
    wxDECLARE_NO_COPY_CLASS(wxWindowDisabler);
701
};
702
703
// ----------------------------------------------------------------------------
704
// Miscellaneous GUI functions
705
// ----------------------------------------------------------------------------
706
707
void WXDLLIMPEXP_CORE wxGetMousePosition( int* x, int* y );
708
709
// ----------------------------------------------------------------------------
710
// X11 Display access
711
// ----------------------------------------------------------------------------
712
713
#if defined(__X__) || (defined(__WXGTK__) && defined(__UNIX__))
714
715
#ifdef __WXGTK__
716
    WXDLLIMPEXP_CORE void *wxGetDisplay();
717
    enum wxDisplayType
718
    {
719
        wxDisplayNone,
720
        wxDisplayX11,
721
        wxDisplayWayland
722
    };
723
    struct wxDisplayInfo
724
    {
725
        void* dpy;
726
        wxDisplayType type;
727
    };
728
    WXDLLIMPEXP_CORE wxDisplayInfo wxGetDisplayInfo();
729
730
    inline struct _XDisplay *wxGetX11Display()
731
    {
732
        const auto& info = wxGetDisplayInfo();
733
        return info.type == wxDisplayX11 ? (_XDisplay*)info.dpy : nullptr;
734
    }
735
#endif
736
737
#ifdef __X__
738
    WXDLLIMPEXP_CORE WXDisplay *wxGetDisplay();
739
    WXDLLIMPEXP_CORE bool wxSetDisplay(const wxString& display_name);
740
    WXDLLIMPEXP_CORE wxString wxGetDisplayName();
741
742
    inline struct _XDisplay *wxGetX11Display()
743
    {
744
        return (_XDisplay *)wxGetDisplay();
745
    }
746
#endif // X
747
748
#endif // X11 || wxGTK
749
750
#endif // wxUSE_GUI
751
752
// ----------------------------------------------------------------------------
753
// wxYield(): these functions are obsolete, please use wxApp methods instead!
754
// ----------------------------------------------------------------------------
755
756
// avoid redeclaring this function here if it had been already declared by
757
// wx/app.h, this results in warnings from g++ with -Wredundant-decls
758
#ifndef wx_YIELD_DECLARED
759
#define wx_YIELD_DECLARED
760
761
// Yield to other apps/messages
762
WXDLLIMPEXP_CORE bool wxYield();
763
764
#endif // wx_YIELD_DECLARED
765
766
// Like wxYield, but fails silently if the yield is recursive.
767
WXDLLIMPEXP_CORE bool wxYieldIfNeeded();
768
769
#ifdef __WINDOWS__
770
WXDLLIMPEXP_CORE bool wxMSWIsOnSecureScreen();
771
#endif // __WINDOWS__
772
773
// ----------------------------------------------------------------------------
774
// Windows resources access
775
// ----------------------------------------------------------------------------
776
777
// Windows only: get user-defined resource from the .res file.
778
#ifdef __WINDOWS__
779
    // default resource type for wxLoadUserResource()
780
    extern WXDLLIMPEXP_DATA_BASE(const wxChar*) wxUserResourceStr;
781
782
    // Return the pointer to the resource data. This pointer is read-only, use
783
    // the overload below if you need to modify the data.
784
    //
785
    // Notice that the resource type can be either a real string or an integer
786
    // produced by MAKEINTRESOURCE(). In particular, any standard resource type,
787
    // i.e any RT_XXX constant, could be passed here.
788
    //
789
    // Returns true on success, false on failure. Doesn't log an error message
790
    // if the resource is not found (because this could be expected) but does
791
    // log one if any other error occurs.
792
    WXDLLIMPEXP_BASE bool
793
    wxLoadUserResource(const void **outData,
794
                       size_t *outLen,
795
                       const wxString& resourceName,
796
                       const wxChar* resourceType = wxUserResourceStr,
797
                       WXHINSTANCE module = nullptr);
798
799
    // This function allocates a new buffer and makes a copy of the resource
800
    // data, remember to delete[] the buffer. And avoid using it entirely if
801
    // the overload above can be used.
802
    //
803
    // Returns nullptr on failure.
804
    WXDLLIMPEXP_BASE char*
805
    wxLoadUserResource(const wxString& resourceName,
806
                       const wxChar* resourceType = wxUserResourceStr,
807
                       int* pLen = nullptr,
808
                       WXHINSTANCE module = nullptr);
809
#endif // __WINDOWS__
810
811
#endif
812
    // _WX_UTILSH__