source: trunk/src/corelib/global/qglobal.cpp@ 769

Last change on this file since 769 was 769, checked in by Dmitry A. Kuminov, 15 years ago

trunk: Merged in qt 4.6.3 sources from branches/vendor/nokia/qt.

File size: 96.3 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
6**
7** This file is part of the QtCore module of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:LGPL$
10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in
14** a written agreement between you and Nokia.
15**
16** GNU Lesser General Public License Usage
17** Alternatively, this file may be used under the terms of the GNU Lesser
18** General Public License version 2.1 as published by the Free Software
19** Foundation and appearing in the file LICENSE.LGPL included in the
20** packaging of this file. Please review the following information to
21** ensure the GNU Lesser General Public License version 2.1 requirements
22** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
23**
24** In addition, as a special exception, Nokia gives you certain additional
25** rights. These rights are described in the Nokia Qt LGPL Exception
26** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you have questions regarding the use of this file, please contact
37** Nokia at [email protected].
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42#include "qplatformdefs.h"
43#include "qstring.h"
44#include "qvector.h"
45#include "qlist.h"
46#include "qthreadstorage.h"
47#include "qdir.h"
48#include "qstringlist.h"
49#include "qdatetime.h"
50
51#ifndef QT_NO_QOBJECT
52#include <private/qthread_p.h>
53#endif
54
55#include <stdio.h>
56#include <stdlib.h>
57#include <limits.h>
58#include <stdarg.h>
59#include <string.h>
60
61#if !defined(Q_OS_WINCE)
62# include <errno.h>
63# if defined(Q_CC_MSVC)
64# include <crtdbg.h>
65# endif
66#endif
67
68#if defined(Q_OS_VXWORKS)
69# include <envLib.h>
70#endif
71
72#if defined(Q_CC_MWERKS) && defined(Q_OS_MACX)
73#include <CoreServices/CoreServices.h>
74#endif
75
76#if defined(Q_OS_SYMBIAN)
77#include <e32def.h>
78#include <e32debug.h>
79#include <f32file.h>
80#include <e32math.h>
81# include "private/qcore_symbian_p.h"
82
83_LIT(qt_S60Filter, "Series60v?.*.sis");
84_LIT(qt_S60SystemInstallDir, "z:\\system\\install\\");
85#endif
86
87QT_BEGIN_NAMESPACE
88
89
90/*!
91 \class QFlag
92 \brief The QFlag class is a helper data type for QFlags.
93
94 It is equivalent to a plain \c int, except with respect to
95 function overloading and type conversions. You should never need
96 to use this class in your applications.
97
98 \sa QFlags
99*/
100
101/*!
102 \fn QFlag::QFlag(int value)
103
104 Constructs a QFlag object that stores the given \a value.
105*/
106
107/*!
108 \fn QFlag::operator int() const
109
110 Returns the value stored by the QFlag object.
111*/
112
113/*!
114 \class QFlags
115 \brief The QFlags class provides a type-safe way of storing
116 OR-combinations of enum values.
117
118
119 \ingroup tools
120
121 The QFlags<Enum> class is a template class, where Enum is an enum
122 type. QFlags is used throughout Qt for storing combinations of
123 enum values.
124
125 The traditional C++ approach for storing OR-combinations of enum
126 values is to use an \c int or \c uint variable. The inconvenience
127 with this approach is that there's no type checking at all; any
128 enum value can be OR'd with any other enum value and passed on to
129 a function that takes an \c int or \c uint.
130
131 Qt uses QFlags to provide type safety. For example, the
132 Qt::Alignment type is simply a typedef for
133 QFlags<Qt::AlignmentFlag>. QLabel::setAlignment() takes a
134 Qt::Alignment parameter, which means that any combination of
135 Qt::AlignmentFlag values,or 0, is legal:
136
137 \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 0
138
139 If you try to pass a value from another enum or just a plain
140 integer other than 0, the compiler will report an error. If you
141 need to cast integer values to flags in a untyped fashion, you can
142 use the explicit QFlags constructor as cast operator.
143
144 If you want to use QFlags for your own enum types, use
145 the Q_DECLARE_FLAGS() and Q_DECLARE_OPERATORS_FOR_FLAGS().
146
147 Example:
148
149 \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 1
150
151 You can then use the \c MyClass::Options type to store
152 combinations of \c MyClass::Option values.
153
154 \section1 Flags and the Meta-Object System
155
156 The Q_DECLARE_FLAGS() macro does not expose the flags to the meta-object
157 system, so they cannot be used by Qt Script or edited in Qt Designer.
158 To make the flags available for these purposes, the Q_FLAGS() macro must
159 be used:
160
161 \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp meta-object flags
162
163 \section1 Naming Convention
164
165 A sensible naming convention for enum types and associated QFlags
166 types is to give a singular name to the enum type (e.g., \c
167 Option) and a plural name to the QFlags type (e.g., \c Options).
168 When a singular name is desired for the QFlags type (e.g., \c
169 Alignment), you can use \c Flag as the suffix for the enum type
170 (e.g., \c AlignmentFlag).
171
172 \sa QFlag
173*/
174
175/*!
176 \typedef QFlags::enum_type
177
178 Typedef for the Enum template type.
179*/
180
181/*!
182 \fn QFlags::QFlags(const QFlags &other)
183
184 Constructs a copy of \a other.
185*/
186
187/*!
188 \fn QFlags::QFlags(Enum flag)
189
190 Constructs a QFlags object storing the given \a flag.
191*/
192
193/*!
194 \fn QFlags::QFlags(Zero zero)
195
196 Constructs a QFlags object with no flags set. \a zero must be a
197 literal 0 value.
198*/
199
200/*!
201 \fn QFlags::QFlags(QFlag value)
202
203 Constructs a QFlags object initialized with the given integer \a
204 value.
205
206 The QFlag type is a helper type. By using it here instead of \c
207 int, we effectively ensure that arbitrary enum values cannot be
208 cast to a QFlags, whereas untyped enum values (i.e., \c int
209 values) can.
210*/
211
212/*!
213 \fn QFlags &QFlags::operator=(const QFlags &other)
214
215 Assigns \a other to this object and returns a reference to this
216 object.
217*/
218
219/*!
220 \fn QFlags &QFlags::operator&=(int mask)
221
222 Performs a bitwise AND operation with \a mask and stores the
223 result in this QFlags object. Returns a reference to this object.
224
225 \sa operator&(), operator|=(), operator^=()
226*/
227
228/*!
229 \fn QFlags &QFlags::operator&=(uint mask)
230
231 \overload
232*/
233
234/*!
235 \fn QFlags &QFlags::operator|=(QFlags other)
236
237 Performs a bitwise OR operation with \a other and stores the
238 result in this QFlags object. Returns a reference to this object.
239
240 \sa operator|(), operator&=(), operator^=()
241*/
242
243/*!
244 \fn QFlags &QFlags::operator|=(Enum other)
245
246 \overload
247*/
248
249/*!
250 \fn QFlags &QFlags::operator^=(QFlags other)
251
252 Performs a bitwise XOR operation with \a other and stores the
253 result in this QFlags object. Returns a reference to this object.
254
255 \sa operator^(), operator&=(), operator|=()
256*/
257
258/*!
259 \fn QFlags &QFlags::operator^=(Enum other)
260
261 \overload
262*/
263
264/*!
265 \fn QFlags::operator int() const
266
267 Returns the value stored in the QFlags object as an integer.
268*/
269
270/*!
271 \fn QFlags QFlags::operator|(QFlags other) const
272
273 Returns a QFlags object containing the result of the bitwise OR
274 operation on this object and \a other.
275
276 \sa operator|=(), operator^(), operator&(), operator~()
277*/
278
279/*!
280 \fn QFlags QFlags::operator|(Enum other) const
281
282 \overload
283*/
284
285/*!
286 \fn QFlags QFlags::operator^(QFlags other) const
287
288 Returns a QFlags object containing the result of the bitwise XOR
289 operation on this object and \a other.
290
291 \sa operator^=(), operator&(), operator|(), operator~()
292*/
293
294/*!
295 \fn QFlags QFlags::operator^(Enum other) const
296
297 \overload
298*/
299
300/*!
301 \fn QFlags QFlags::operator&(int mask) const
302
303 Returns a QFlags object containing the result of the bitwise AND
304 operation on this object and \a mask.
305
306 \sa operator&=(), operator|(), operator^(), operator~()
307*/
308
309/*!
310 \fn QFlags QFlags::operator&(uint mask) const
311
312 \overload
313*/
314
315/*!
316 \fn QFlags QFlags::operator&(Enum mask) const
317
318 \overload
319*/
320
321/*!
322 \fn QFlags QFlags::operator~() const
323
324 Returns a QFlags object that contains the bitwise negation of
325 this object.
326
327 \sa operator&(), operator|(), operator^()
328*/
329
330/*!
331 \fn bool QFlags::operator!() const
332
333 Returns true if no flag is set (i.e., if the value stored by the
334 QFlags object is 0); otherwise returns false.
335*/
336
337/*!
338 \fn bool QFlags::testFlag(Enum flag) const
339 \since 4.2
340
341 Returns true if the \a flag is set, otherwise false.
342*/
343
344/*!
345 \macro Q_DISABLE_COPY(Class)
346 \relates QObject
347
348 Disables the use of copy constructors and assignment operators
349 for the given \a Class.
350
351 Instances of subclasses of QObject should not be thought of as
352 values that can be copied or assigned, but as unique identities.
353 This means that when you create your own subclass of QObject
354 (director or indirect), you should \e not give it a copy constructor
355 or an assignment operator. However, it may not enough to simply
356 omit them from your class, because, if you mistakenly write some code
357 that requires a copy constructor or an assignment operator (it's easy
358 to do), your compiler will thoughtfully create it for you. You must
359 do more.
360
361 The curious user will have seen that the Qt classes derived
362 from QObject typically include this macro in a private section:
363
364 \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 43
365
366 It declares a copy constructor and an assignment operator in the
367 private section, so that if you use them by mistake, the compiler
368 will report an error.
369
370 \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 44
371
372 But even this might not catch absolutely every case. You might be
373 tempted to do something like this:
374
375 \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 45
376
377 First of all, don't do that. Most compilers will generate code that
378 uses the copy constructor, so the privacy violation error will be
379 reported, but your C++ compiler is not required to generate code for
380 this statement in a specific way. It could generate code using
381 \e{neither} the copy constructor \e{nor} the assignment operator we
382 made private. In that case, no error would be reported, but your
383 application would probably crash when you called a member function
384 of \c{w}.
385*/
386
387/*!
388 \macro Q_DECLARE_FLAGS(Flags, Enum)
389 \relates QFlags
390
391 The Q_DECLARE_FLAGS() macro expands to
392
393 \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 2
394
395 \a Enum is the name of an existing enum type, whereas \a Flags is
396 the name of the QFlags<\e{Enum}> typedef.
397
398 See the QFlags documentation for details.
399
400 \sa Q_DECLARE_OPERATORS_FOR_FLAGS()
401*/
402
403/*!
404 \macro Q_DECLARE_OPERATORS_FOR_FLAGS(Flags)
405 \relates QFlags
406
407 The Q_DECLARE_OPERATORS_FOR_FLAGS() macro declares global \c
408 operator|() functions for \a Flags, which is of type QFlags<T>.
409
410 See the QFlags documentation for details.
411
412 \sa Q_DECLARE_FLAGS()
413*/
414
415/*!
416 \headerfile <QtGlobal>
417 \title Global Qt Declarations
418 \ingroup funclists
419
420 \brief The <QtGlobal> header file includes the fundamental global
421 declarations. It is included by most other Qt header files.
422
423 The global declarations include \l{types}, \l{functions} and
424 \l{macros}.
425
426 The type definitions are partly convenience definitions for basic
427 types (some of which guarantee certain bit-sizes on all platforms
428 supported by Qt), partly types related to Qt message handling. The
429 functions are related to generating messages, Qt version handling
430 and comparing and adjusting object values. And finally, some of
431 the declared macros enable programmers to add compiler or platform
432 specific code to their applications, while others are convenience
433 macros for larger operations.
434
435 \section1 Types
436
437 The header file declares several type definitions that guarantee a
438 specified bit-size on all platforms supported by Qt for various
439 basic types, for example \l qint8 which is a signed char
440 guaranteed to be 8-bit on all platforms supported by Qt. The
441 header file also declares the \l qlonglong type definition for \c
442 {long long int } (\c __int64 on Windows).
443
444 Several convenience type definitions are declared: \l qreal for \c
445 double, \l uchar for \c unsigned char, \l uint for \c unsigned
446 int, \l ulong for \c unsigned long and \l ushort for \c unsigned
447 short.
448
449 Finally, the QtMsgType definition identifies the various messages
450 that can be generated and sent to a Qt message handler;
451 QtMsgHandler is a type definition for a pointer to a function with
452 the signature \c {void myMsgHandler(QtMsgType, const char *)}.
453
454 \section1 Functions
455
456 The <QtGlobal> header file contains several functions comparing
457 and adjusting an object's value. These functions take a template
458 type as argument: You can retrieve the absolute value of an object
459 using the qAbs() function, and you can bound a given object's
460 value by given minimum and maximum values using the qBound()
461 function. You can retrieve the minimum and maximum of two given
462 objects using qMin() and qMax() respectively. All these functions
463 return a corresponding template type; the template types can be
464 replaced by any other type.
465
466 Example:
467
468 \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 3
469
470 <QtGlobal> also contains functions that generate messages from the
471 given string argument: qCritical(), qDebug(), qFatal() and
472 qWarning(). These functions call the message handler with the
473 given message.
474
475 Example:
476
477 \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 4
478
479 The remaining functions are qRound() and qRound64(), which both
480 accept a \l qreal value as their argument returning the value
481 rounded up to the nearest integer and 64-bit integer respectively,
482 the qInstallMsgHandler() function which installs the given
483 QtMsgHandler, and the qVersion() function which returns the
484 version number of Qt at run-time as a string.
485
486 \section1 Macros
487
488 The <QtGlobal> header file provides a range of macros (Q_CC_*)
489 that are defined if the application is compiled using the
490 specified platforms. For example, the Q_CC_SUN macro is defined if
491 the application is compiled using Forte Developer, or Sun Studio
492 C++. The header file also declares a range of macros (Q_OS_*)
493 that are defined for the specified platforms. For example,
494 Q_OS_X11 which is defined for the X Window System.
495
496 The purpose of these macros is to enable programmers to add
497 compiler or platform specific code to their application.
498
499 The remaining macros are convenience macros for larger operations:
500 The QT_TRANSLATE_NOOP() and QT_TR_NOOP() macros provide the
501 possibility of marking text for dynamic translation,
502 i.e. translation without changing the stored source text. The
503 Q_ASSERT() and Q_ASSERT_X() enables warning messages of various
504 level of refinement. The Q_FOREACH() and foreach() macros
505 implement Qt's foreach loop.
506
507 The Q_INT64_C() and Q_UINT64_C() macros wrap signed and unsigned
508 64-bit integer literals in a platform-independent way. The
509 Q_CHECK_PTR() macro prints a warning containing the source code's
510 file name and line number, saying that the program ran out of
511 memory, if the pointer is 0. The qPrintable() macro represent an
512 easy way of printing text.
513
514 Finally, the QT_POINTER_SIZE macro expands to the size of a
515 pointer in bytes, and the QT_VERSION and QT_VERSION_STR macros
516 expand to a numeric value or a string, respectively, specifying
517 Qt's version number, i.e the version the application is compiled
518 against.
519
520 \sa <QtAlgorithms>, QSysInfo
521*/
522
523/*!
524 \typedef qreal
525 \relates <QtGlobal>
526
527 Typedef for \c double on all platforms except for those using CPUs with
528 ARM architectures.
529 On ARM-based platforms, \c qreal is a typedef for \c float for performance
530 reasons.
531*/
532
533/*! \typedef uchar
534 \relates <QtGlobal>
535
536 Convenience typedef for \c{unsigned char}.
537*/
538
539/*!
540 \fn qt_set_sequence_auto_mnemonic(bool on)
541 \relates <QtGlobal>
542
543 Enables automatic mnemonics on Mac if \a on is true; otherwise
544 this feature is disabled.
545
546 Note that this function is only available on Mac where mnemonics
547 are disabled by default.
548
549 To access to this function, use an extern declaration:
550 extern void qt_set_sequence_auto_mnemonic(bool b);
551
552 \sa {QShortcut#mnemonic}{QShortcut}
553*/
554
555/*! \typedef ushort
556 \relates <QtGlobal>
557
558 Convenience typedef for \c{unsigned short}.
559*/
560
561/*! \typedef uint
562 \relates <QtGlobal>
563
564 Convenience typedef for \c{unsigned int}.
565*/
566
567/*! \typedef ulong
568 \relates <QtGlobal>
569
570 Convenience typedef for \c{unsigned long}.
571*/
572
573/*! \typedef qint8
574 \relates <QtGlobal>
575
576 Typedef for \c{signed char}. This type is guaranteed to be 8-bit
577 on all platforms supported by Qt.
578*/
579
580/*!
581 \typedef quint8
582 \relates <QtGlobal>
583
584 Typedef for \c{unsigned char}. This type is guaranteed to
585 be 8-bit on all platforms supported by Qt.
586*/
587
588/*! \typedef qint16
589 \relates <QtGlobal>
590
591 Typedef for \c{signed short}. This type is guaranteed to be
592 16-bit on all platforms supported by Qt.
593*/
594
595/*!
596 \typedef quint16
597 \relates <QtGlobal>
598
599 Typedef for \c{unsigned short}. This type is guaranteed to
600 be 16-bit on all platforms supported by Qt.
601*/
602
603/*! \typedef qint32
604 \relates <QtGlobal>
605
606 Typedef for \c{signed int}. This type is guaranteed to be 32-bit
607 on all platforms supported by Qt.
608*/
609
610/*!
611 \typedef quint32
612 \relates <QtGlobal>
613
614 Typedef for \c{unsigned int}. This type is guaranteed to
615 be 32-bit on all platforms supported by Qt.
616*/
617
618/*! \typedef qint64
619 \relates <QtGlobal>
620
621 Typedef for \c{long long int} (\c __int64 on Windows). This type
622 is guaranteed to be 64-bit on all platforms supported by Qt.
623
624 Literals of this type can be created using the Q_INT64_C() macro:
625
626 \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 5
627
628 \sa Q_INT64_C(), quint64, qlonglong
629*/
630
631/*!
632 \typedef quint64
633 \relates <QtGlobal>
634
635 Typedef for \c{unsigned long long int} (\c{unsigned __int64} on
636 Windows). This type is guaranteed to be 64-bit on all platforms
637 supported by Qt.