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