1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the QtCore module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40#include "qpoint.h"
41#include "qdatastream.h"
42
43#include <private/qdebug_p.h>
44#include <QtCore/qhashfunctions.h>
45
46QT_BEGIN_NAMESPACE
47
48/*!
49 \class QPoint
50 \inmodule QtCore
51 \ingroup painting
52 \reentrant
53
54 \brief The QPoint class defines a point in the plane using integer
55 precision.
56
57 A point is specified by a x coordinate and an y coordinate which
58 can be accessed using the x() and y() functions. The isNull()
59 function returns \c true if both x and y are set to 0. The
60 coordinates can be set (or altered) using the setX() and setY()
61 functions, or alternatively the rx() and ry() functions which
62 return references to the coordinates (allowing direct
63 manipulation).
64
65 Given a point \e p, the following statements are all equivalent:
66
67 \snippet code/src_corelib_tools_qpoint.cpp 0
68
69 A QPoint object can also be used as a vector: Addition and
70 subtraction are defined as for vectors (each component is added
71 separately). A QPoint object can also be divided or multiplied by
72 an \c int or a \c qreal.
73
74 In addition, the QPoint class provides the manhattanLength()
75 function which gives an inexpensive approximation of the length of
76 the QPoint object interpreted as a vector. Finally, QPoint objects
77 can be streamed as well as compared.
78
79 \sa QPointF, QPolygon
80*/
81
82
83/*****************************************************************************
84 QPoint member functions
85 *****************************************************************************/
86
87/*!
88 \fn QPoint::QPoint()
89
90 Constructs a null point, i.e. with coordinates (0, 0)
91
92 \sa isNull()
93*/
94
95/*!
96 \fn QPoint::QPoint(int xpos, int ypos)
97
98 Constructs a point with the given coordinates (\a xpos, \a ypos).
99
100 \sa setX(), setY()
101*/
102
103/*!
104 \fn bool QPoint::isNull() const
105
106 Returns \c true if both the x and y coordinates are set to 0,
107 otherwise returns \c false.
108*/
109
110/*!
111 \fn int QPoint::x() const
112
113 Returns the x coordinate of this point.
114
115 \sa setX(), rx()
116*/
117
118/*!
119 \fn int QPoint::y() const
120
121 Returns the y coordinate of this point.
122
123 \sa setY(), ry()
124*/
125
126/*!
127 \fn void QPoint::setX(int x)
128
129 Sets the x coordinate of this point to the given \a x coordinate.
130
131 \sa x(), setY()
132*/
133
134/*!
135 \fn void QPoint::setY(int y)
136
137 Sets the y coordinate of this point to the given \a y coordinate.
138
139 \sa y(), setX()
140*/
141
142/*!
143 \fn QPoint::transposed() const
144 \since 5.14
145
146 Returns a point with x and y coordinates exchanged:
147 \code
148 QPoint{1, 2}.transposed() // {2, 1}
149 \endcode
150
151 \sa x(), y(), setX(), setY()
152*/
153
154/*!
155 \fn int &QPoint::rx()
156
157 Returns a reference to the x coordinate of this point.
158
159 Using a reference makes it possible to directly manipulate x. For example:
160
161 \snippet code/src_corelib_tools_qpoint.cpp 1
162
163 \sa x(), setX()
164*/
165
166/*!
167 \fn int &QPoint::ry()
168
169 Returns a reference to the y coordinate of this point.
170
171 Using a reference makes it possible to directly manipulate y. For
172 example:
173
174 \snippet code/src_corelib_tools_qpoint.cpp 2
175
176 \sa y(), setY()
177*/
178
179
180/*!
181 \fn QPoint &QPoint::operator+=(const QPoint &point)
182
183 Adds the given \a point to this point and returns a reference to
184 this point. For example:
185
186 \snippet code/src_corelib_tools_qpoint.cpp 3
187
188 \sa operator-=()
189*/
190
191/*!
192 \fn QPoint &QPoint::operator-=(const QPoint &point)
193
194 Subtracts the given \a point from this point and returns a
195 reference to this point. For example:
196
197 \snippet code/src_corelib_tools_qpoint.cpp 4
198
199 \sa operator+=()
200*/
201
202/*!
203 \fn QPoint &QPoint::operator*=(float factor)
204
205 Multiplies this point's coordinates by the given \a factor, and
206 returns a reference to this point.
207
208 Note that the result is rounded to the nearest integer as points are held as
209 integers. Use QPointF for floating point accuracy.
210
211 \sa operator/=()
212*/
213
214/*!
215 \fn QPoint &QPoint::operator*=(double factor)
216
217 Multiplies this point's coordinates by the given \a factor, and
218 returns a reference to this point. For example:
219
220 \snippet code/src_corelib_tools_qpoint.cpp 5
221
222 Note that the result is rounded to the nearest integer as points are held as
223 integers. Use QPointF for floating point accuracy.
224
225 \sa operator/=()
226*/
227
228/*!
229 \fn QPoint &QPoint::operator*=(int factor)
230
231 Multiplies this point's coordinates by the given \a factor, and
232 returns a reference to this point.
233
234 \sa operator/=()
235*/
236
237/*!
238 \fn static int QPoint::dotProduct(const QPoint &p1, const QPoint &p2)
239 \since 5.1
240
241 \snippet code/src_corelib_tools_qpoint.cpp 16
242
243 Returns the dot product of \a p1 and \a p2.
244*/
245
246/*!
247 \fn bool QPoint::operator==(const QPoint &p1, const QPoint &p2)
248
249 Returns \c true if \a p1 and \a p2 are equal; otherwise returns
250 false.
251*/
252
253/*!
254 \fn bool QPoint::operator!=(const QPoint &p1, const QPoint &p2)
255
256 Returns \c true if \a p1 and \a p2 are not equal; otherwise returns \c false.
257*/
258
259/*!
260 \fn QPoint QPoint::operator+(const QPoint &p1, const QPoint &p2)
261
262 Returns a QPoint object that is the sum of the given points, \a p1
263 and \a p2; each component is added separately.
264
265 \sa QPoint::operator+=()
266*/
267
268/*!
269 \fn Point QPoint::operator-(const QPoint &p1, const QPoint &p2)
270
271 Returns a QPoint object that is formed by subtracting \a p2 from
272 \a p1; each component is subtracted separately.
273
274 \sa QPoint::operator-=()
275*/
276
277/*!
278 \fn QPoint QPoint::operator*(const QPoint &point, float factor)
279
280 Returns a copy of the given \a point multiplied by the given \a factor.
281
282 Note that the result is rounded to the nearest integer as points
283 are held as integers. Use QPointF for floating point accuracy.
284
285 \sa QPoint::operator*=()
286*/
287
288/*!
289 \fn QPoint QPoint::operator*(const QPoint &point, double factor)
290
291 Returns a copy of the given \a point multiplied by the given \a factor.
292
293 Note that the result is rounded to the nearest integer as points
294 are held as integers. Use QPointF for floating point accuracy.
295
296 \sa QPoint::operator*=()
297*/
298
299/*!
300 \fn QPoint QPoint::operator*(const QPoint &point, int factor)
301
302 Returns a copy of the given \a point multiplied by the given \a factor.
303
304 \sa QPoint::operator*=()
305*/
306
307/*!
308 \fn QPoint QPoint::operator*(float factor, const QPoint &point)
309 \overload
310
311 Returns a copy of the given \a point multiplied by the given \a factor.
312
313 Note that the result is rounded to the nearest integer as points
314 are held as integers. Use QPointF for floating point accuracy.
315
316 \sa QPoint::operator*=()
317*/
318
319/*!
320 \fn QPoint QPoint::operator*(double factor, const QPoint &point)
321 \overload
322
323 Returns a copy of the given \a point multiplied by the given \a factor.
324
325 Note that the result is rounded to the nearest integer as points
326 are held as integers. Use QPointF for floating point accuracy.
327
328 \sa QPoint::operator*=()
329*/
330
331/*!
332 \fn QPoint QPoint::operator*(int factor, const QPoint &point)
333 \overload
334
335 Returns a copy of the given \a point multiplied by the given \a factor.
336
337 \sa QPoint::operator*=()
338*/
339
340/*!
341 \fn QPoint QPoint::operator+(const QPoint &point)
342 \since 5.0
343
344 Returns \a point unmodified.
345*/
346
347/*!
348 \fn QPoint QPoint::operator-(const QPoint &point)
349 \overload
350
351 Returns a QPoint object that is formed by changing the sign of
352 both components of the given \a point.
353
354 Equivalent to \c{QPoint(0,0) - point}.
355*/
356
357/*!
358 \fn QPoint &QPoint::operator/=(qreal divisor)
359 \overload
360
361 Divides both x and y by the given \a divisor, and returns a reference to this
362 point. For example:
363
364 \snippet code/src_corelib_tools_qpoint.cpp 6
365
366 Note that the result is rounded to the nearest integer as points are held as
367 integers. Use QPointF for floating point accuracy.
368
369 \sa operator*=()
370*/
371
372/*!
373 \fn const QPoint QPoint::operator/(const QPoint &point, qreal divisor)
374
375 Returns the QPoint formed by dividing both components of the given \a point
376 by the given \a divisor.
377
378 Note that the result is rounded to the nearest integer as points are held as
379 integers. Use QPointF for floating point accuracy.
380
381 \sa QPoint::operator/=()
382*/
383
384/*****************************************************************************
385 QPoint stream functions
386 *****************************************************************************/
387#ifndef QT_NO_DATASTREAM
388/*!
389 \fn QDataStream &operator<<(QDataStream &stream, const QPoint &point)
390 \relates QPoint
391
392 Writes the given \a point to the given \a stream and returns a
393 reference to the stream.
394
395 \sa {Serializing Qt Data Types}
396*/
397
398QDataStream &operator<<(QDataStream &s, const QPoint &p)
399{
400 if (s.version() == 1)
401 s << (qint16)p.x() << (qint16)p.y();
402 else
403 s << (qint32)p.x() << (qint32)p.y();
404 return s;
405}
406
407/*!
408 \fn QDataStream &operator>>(QDataStream &stream, QPoint &point)
409 \relates QPoint
410
411 Reads a point from the given \a stream into the given \a point
412 and returns a reference to the stream.
413
414 \sa {Serializing Qt Data Types}
415*/
416
417QDataStream &operator>>(QDataStream &s, QPoint &p)
418{
419 if (s.version() == 1) {
420 qint16 x, y;
421 s >> x; p.rx() = x;
422 s >> y; p.ry() = y;
423 }
424 else {
425 qint32 x, y;
426 s >> x; p.rx() = x;
427 s >> y; p.ry() = y;
428 }
429 return s;
430}
431
432#endif // QT_NO_DATASTREAM
433/*!
434 \fn int QPoint::manhattanLength() const
435
436 Returns the sum of the absolute values of x() and y(),
437 traditionally known as the "Manhattan length" of the vector from
438 the origin to the point. For example:
439
440 \snippet code/src_corelib_tools_qpoint.cpp 7
441
442 This is a useful, and quick to calculate, approximation to the
443 true length:
444
445 \snippet code/src_corelib_tools_qpoint.cpp 8
446
447 The tradition of "Manhattan length" arises because such distances
448 apply to travelers who can only travel on a rectangular grid, like
449 the streets of Manhattan.
450*/
451
452#ifndef QT_NO_DEBUG_STREAM
453QDebug operator<<(QDebug dbg, const QPoint &p)
454{
455 QDebugStateSaver saver(dbg);
456 dbg.nospace();
457 dbg << "QPoint" << '(';
458 QtDebugUtils::formatQPoint(dbg, p);
459 dbg << ')';
460 return dbg;
461}
462
463QDebug operator<<(QDebug dbg, const QPointF &p)
464{
465 QDebugStateSaver saver(dbg);
466 dbg.nospace();
467 dbg << "QPointF" << '(';
468 QtDebugUtils::formatQPoint(dbg, p);
469 dbg << ')';
470 return dbg;
471}
472#endif
473
474/*!
475 \fn size_t qHash(QPoint key, size_t seed = 0)
476 \relates QHash
477 \since 6.0
478
479 Returns the hash value for the \a key, using \a seed to seed the
480 calculation.
481*/
482size_t qHash(QPoint key, size_t seed) noexcept
483{
484 return qHashMulti(seed, key.x(), key.y());
485}
486
487/*!
488 \class QPointF
489 \inmodule QtCore
490 \ingroup painting
491 \reentrant
492
493 \brief The QPointF class defines a point in the plane using
494 floating point precision.
495
496 A point is specified by a x coordinate and an y coordinate which
497 can be accessed using the x() and y() functions. The coordinates
498 of the point are specified using floating point numbers for
499 accuracy. The isNull() function returns \c true if both x and y are
500 set to 0.0. The coordinates can be set (or altered) using the setX()
501 and setY() functions, or alternatively the rx() and ry() functions which
502 return references to the coordinates (allowing direct
503 manipulation).
504
505 Given a point \e p, the following statements are all equivalent:
506
507 \snippet code/src_corelib_tools_qpoint.cpp 9
508
509 A QPointF object can also be used as a vector: Addition and
510 subtraction are defined as for vectors (each component is added
511 separately). A QPointF object can also be divided or multiplied by
512 an \c int or a \c qreal.
513
514 In addition, the QPointF class provides a constructor converting a
515 QPoint object into a QPointF object, and a corresponding toPoint()
516 function which returns a QPoint copy of \e this point. Finally,
517 QPointF objects can be streamed as well as compared.
518
519 \sa QPoint, QPolygonF
520*/
521
522/*!
523 \fn QPointF::QPointF()
524
525 Constructs a null point, i.e. with coordinates (0.0, 0.0)
526
527 \sa isNull()
528*/
529
530/*!
531 \fn QPointF::QPointF(const QPoint &point)
532
533 Constructs a copy of the given \a point.
534
535 \sa toPoint()
536*/
537
538/*!
539 \fn QPointF::QPointF(qreal xpos, qreal ypos)
540
541 Constructs a point with the given coordinates (\a xpos, \a ypos).
542
543 \sa setX(), setY()
544*/
545
546/*!
547 \fn bool QPointF::isNull() const
548
549 Returns \c true if both the x and y coordinates are set to 0.0 (ignoring
550 the sign); otherwise returns \c false.
551*/
552
553
554/*!
555 \fn qreal QPointF::manhattanLength() const
556 \since 4.6
557
558 Returns the sum of the absolute values of x() and y(),
559 traditionally known as the "Manhattan length" of the vector from
560 the origin to the point.
561
562 \sa QPoint::manhattanLength()
563*/
564
565/*!
566 \fn qreal QPointF::x() const
567
568 Returns the x coordinate of this point.
569
570 \sa setX(), rx()
571*/
572
573/*!
574 \fn qreal QPointF::y() const
575
576 Returns the y coordinate of this point.
577
578 \sa setY(), ry()
579*/
580
581/*!
582 \fn void QPointF::setX(qreal x)
583
584 Sets the x coordinate of this point to the given \a x coordinate.
585
586 \sa x(), setY()
587*/
588
589/*!
590 \fn void QPointF::setY(qreal y)
591
592 Sets the y coordinate of this point to the given \a y coordinate.
593
594 \sa y(), setX()
595*/
596
597/*!
598 \fn QPointF::transposed() const
599 \since 5.14
600
601 Returns a point with x and y coordinates exchanged:
602 \code
603 QPointF{1.0, 2.0}.transposed() // {2.0, 1.0}
604 \endcode
605
606 \sa x(), y(), setX(), setY()
607*/
608
609/*!
610 \fn qreal& QPointF::rx()
611
612 Returns a reference to the x coordinate of this point.
613
614 Using a reference makes it possible to directly manipulate x. For example:
615
616 \snippet code/src_corelib_tools_qpoint.cpp 10
617
618 \sa x(), setX()
619*/
620
621/*!
622 \fn qreal& QPointF::ry()
623
624 Returns a reference to the y coordinate of this point.
625
626 Using a reference makes it possible to directly manipulate y. For example:
627
628 \snippet code/src_corelib_tools_qpoint.cpp 11
629
630 \sa y(), setY()
631*/
632
633/*!
634 \fn QPointF& QPointF::operator+=(const QPointF &point)
635
636 Adds the given \a point to this point and returns a reference to
637 this point. For example:
638
639 \snippet code/src_corelib_tools_qpoint.cpp 12
640
641 \sa operator-=()
642*/
643
644/*!
645 \fn QPointF& QPointF::operator-=(const QPointF &point)
646
647 Subtracts the given \a point from this point and returns a reference
648 to this point. For example:
649
650 \snippet code/src_corelib_tools_qpoint.cpp 13
651
652 \sa operator+=()
653*/
654
655/*!
656 \fn QPointF& QPointF::operator*=(qreal factor)
657
658 Multiplies this point's coordinates by the given \a factor, and
659 returns a reference to this point. For example:
660
661 \snippet code/src_corelib_tools_qpoint.cpp 14
662
663 \sa operator/=()
664*/
665
666/*!
667 \fn QPointF& QPointF::operator/=(qreal divisor)
668
669 Divides both x and y by the given \a divisor, and returns a reference
670 to this point. For example:
671
672 \snippet code/src_corelib_tools_qpoint.cpp 15
673
674 \sa operator*=()
675*/
676
677/*!
678 \fn QPointF QPointF::operator+(const QPointF &p1, const QPointF &p2)
679
680 Returns a QPointF object that is the sum of the given points, \a p1
681 and \a p2; each component is added separately.
682
683 \sa QPointF::operator+=()
684*/
685
686/*!
687 \fn QPointF QPointF::operator-(const QPointF &p1, const QPointF &p2)
688
689 Returns a QPointF object that is formed by subtracting \a p2 from \a p1;
690 each component is subtracted separately.
691
692 \sa QPointF::operator-=()
693*/
694
695/*!
696 \fn QPointF QPointF::operator*(const QPointF &point, qreal factor)
697
698 Returns a copy of the given \a point, multiplied by the given \a factor.
699
700 \sa QPointF::operator*=()
701*/
702
703/*!
704 \fn QPointF QPointF::operator*(qreal factor, const QPointF &point)
705
706 \overload
707
708 Returns a copy of the given \a point, multiplied by the given \a factor.
709*/
710
711/*!
712 \fn QPointF QPointF::operator+(const QPointF &point)
713 \since 5.0
714
715 Returns \a point unmodified.
716*/
717
718/*!
719 \fn QPointF QPointF::operator-(const QPointF &point)
720 \overload
721
722 Returns a QPointF object that is formed by changing the sign of
723 both components of the given \a point.
724
725 Equivalent to \c {QPointF(0,0) - point}.
726*/
727
728/*!
729 \fn QPointF QPointF::operator/(const QPointF &point, qreal divisor)
730
731 Returns the QPointF object formed by dividing both components of
732 the given \a point by the given \a divisor.
733
734 \sa QPointF::operator/=()
735*/
736
737/*!
738 \fn QPoint QPointF::toPoint() const
739
740 Rounds the coordinates of this point to the nearest integer, and
741 returns a QPoint object with the rounded coordinates.
742
743 \sa QPointF()
744*/
745
746/*!
747 \fn static qreal QPointF::dotProduct(const QPointF &p1, const QPointF &p2)
748 \since 5.1
749
750 \snippet code/src_corelib_tools_qpoint.cpp 17
751
752 Returns the dot product of \a p1 and \a p2.
753*/
754
755/*!
756 \fn bool QPointF::operator==(const QPointF &p1, const QPointF &p2)
757
758 Returns \c true if \a p1 is approximately equal to \a p2; otherwise
759 returns \c false.
760
761 \warning This function does not check for strict equality; instead,
762 it uses a fuzzy comparison to compare the points' coordinates.
763
764 \sa qFuzzyCompare
765*/
766
767/*!
768 \fn bool QPointF::operator!=(const QPointF &p1, const QPointF &p2);
769
770 Returns \c true if \a p1 is sufficiently different from \a p2;
771 otherwise returns \c false.
772
773 \warning This function does not check for strict inequality; instead,
774 it uses a fuzzy comparison to compare the points' coordinates.
775
776 \sa qFuzzyCompare
777*/
778
779#ifndef QT_NO_DATASTREAM
780/*!
781 \fn QDataStream &operator<<(QDataStream &stream, const QPointF &point)
782 \relates QPointF
783
784 Writes the given \a point to the given \a stream and returns a
785 reference to the stream.
786
787 \sa {Serializing Qt Data Types}
788*/
789
790QDataStream &operator<<(QDataStream &s, const QPointF &p)
791{
792 s << double(p.x()) << double(p.y());
793 return s;
794}
795
796/*!
797 \fn QDataStream &operator>>(QDataStream &stream, QPointF &point)
798 \relates QPointF
799
800 Reads a point from the given \a stream into the given \a point
801 and returns a reference to the stream.
802
803 \sa {Serializing Qt Data Types}
804*/
805
806QDataStream &operator>>(QDataStream &s, QPointF &p)
807{
808 double x, y;
809 s >> x;
810 s >> y;
811 p.setX(qreal(x));
812 p.setY(qreal(y));
813 return s;
814}
815#endif // QT_NO_DATASTREAM
816
817QT_END_NAMESPACE
818