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

source code of qtbase/src/corelib/tools/qpoint.cpp