1// Copyright (C) 2022 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qmargins.h"
5#include "qdatastream.h"
6
7#include <private/qdebug_p.h>
8
9QT_BEGIN_NAMESPACE
10
11/*!
12 \class QMargins
13 \inmodule QtCore
14 \ingroup painting
15 \since 4.6
16
17 \compares equality
18 \compareswith equality QMarginsF
19 \endcompareswith
20
21 \brief The QMargins class defines the four margins of a rectangle.
22
23 QMargin defines a set of four margins; left, top, right, and bottom,
24 that describe the size of the borders surrounding a rectangle.
25
26 The isNull() function returns \c true only if all margins are set to zero.
27
28 QMargin objects can be streamed as well as compared.
29*/
30
31
32/*****************************************************************************
33 QMargins member functions
34 *****************************************************************************/
35
36/*!
37 \fn QMargins::QMargins()
38
39 Constructs a margins object with all margins set to 0.
40
41 \sa isNull()
42*/
43
44/*!
45 \fn QMargins::QMargins(int left, int top, int right, int bottom)
46
47 Constructs margins with the given \a left, \a top, \a right, and \a bottom
48
49 \sa setLeft(), setRight(), setTop(), setBottom()
50*/
51
52/*!
53 \fn bool QMargins::isNull() const
54
55 Returns \c true if all margins are is 0; otherwise returns
56 false.
57*/
58
59
60/*!
61 \fn int QMargins::left() const
62
63 Returns the left margin.
64
65 \sa setLeft()
66*/
67
68/*!
69 \fn int QMargins::top() const
70
71 Returns the top margin.
72
73 \sa setTop()
74*/
75
76/*!
77 \fn int QMargins::right() const
78
79 Returns the right margin.
80*/
81
82/*!
83 \fn int QMargins::bottom() const
84
85 Returns the bottom margin.
86*/
87
88
89/*!
90 \fn void QMargins::setLeft(int left)
91
92 Sets the left margin to \a left.
93*/
94
95/*!
96 \fn void QMargins::setTop(int Top)
97
98 Sets the Top margin to \a Top.
99*/
100
101/*!
102 \fn void QMargins::setRight(int right)
103
104 Sets the right margin to \a right.
105*/
106
107/*!
108 \fn void QMargins::setBottom(int bottom)
109
110 Sets the bottom margin to \a bottom.
111*/
112
113/*!
114 \fn bool QMargins::operator==(const QMargins &lhs, const QMargins &rhs)
115
116 Returns \c true if \a lhs and \a rhs are equal; otherwise returns \c false.
117*/
118
119/*!
120 \fn bool QMargins::operator!=(const QMargins &lhs, const QMargins &rhs)
121
122 Returns \c true if \a lhs and \a rhs are different; otherwise returns \c false.
123*/
124
125/*!
126 \fn QMargins operator+(const QMargins &m1, const QMargins &m2)
127 \relates QMargins
128
129 Returns a QMargins object that is the sum of the given margins, \a m1
130 and \a m2; each component is added separately.
131
132 \sa QMargins::operator+=(), QMargins::operator-=()
133
134 \since 5.1
135*/
136
137/*!
138 \fn QMargins operator-(const QMargins &m1, const QMargins &m2)
139 \relates QMargins
140
141 Returns a QMargins object that is formed by subtracting \a m2 from
142 \a m1; each component is subtracted separately.
143
144 \sa QMargins::operator+=(), QMargins::operator-=()
145
146 \since 5.1
147*/
148
149/*!
150 \fn QMargins operator+(const QMargins &lhs, int rhs)
151 \relates QMargins
152
153 Returns a QMargins object that is formed by adding \a rhs to
154 \a lhs.
155
156 \sa QMargins::operator+=(), QMargins::operator-=()
157
158 \since 5.3
159*/
160
161/*!
162 \fn QMargins operator+(int lhs, const QMargins &rhs)
163 \relates QMargins
164
165 Returns a QMargins object that is formed by adding \a lhs to
166 \a rhs.
167
168 \sa QMargins::operator+=(), QMargins::operator-=()
169
170 \since 5.3
171*/
172
173/*!
174 \fn QMargins operator-(const QMargins &lhs, int rhs)
175 \relates QMargins
176
177 Returns a QMargins object that is formed by subtracting \a rhs from
178 \a lhs.
179
180 \sa QMargins::operator+=(), QMargins::operator-=()
181
182 \since 5.3
183*/
184
185/*!
186 \fn QMargins operator*(const QMargins &margins, int factor)
187 \relates QMargins
188
189 Returns a QMargins object that is formed by multiplying each component
190 of the given \a margins by \a factor.
191
192 \sa QMargins::operator*=(), QMargins::operator/=()
193
194 \since 5.1
195*/
196
197/*!
198 \fn QMargins operator*(int factor, const QMargins &margins)
199 \relates QMargins
200 \overload
201
202 Returns a QMargins object that is formed by multiplying each component
203 of the given \a margins by \a factor.
204
205 \sa QMargins::operator*=(), QMargins::operator/=()
206
207 \since 5.1
208*/
209
210/*!
211 \fn QMargins operator*(const QMargins &margins, qreal factor)
212 \relates QMargins
213 \overload
214
215 Returns a QMargins object that is formed by multiplying each component
216 of the given \a margins by \a factor.
217
218 \sa QMargins::operator*=(), QMargins::operator/=()
219
220 \since 5.1
221*/
222
223/*!
224 \fn QMargins operator*(qreal factor, const QMargins &margins)
225 \relates QMargins
226 \overload
227
228 Returns a QMargins object that is formed by multiplying each component
229 of the given \a margins by \a factor.
230
231 \sa QMargins::operator*=(), QMargins::operator/=()
232
233 \since 5.1
234*/
235
236/*!
237 \fn QMargins operator/(const QMargins &margins, int divisor)
238 \relates QMargins
239
240 Returns a QMargins object that is formed by dividing the components of
241 the given \a margins by the given \a divisor.
242
243 \sa QMargins::operator*=(), QMargins::operator/=()
244
245 \since 5.1
246*/
247
248/*!
249 \fn QMargins operator/(const QMargins &, qreal)
250 \relates QMargins
251 \overload
252
253 Returns a QMargins object that is formed by dividing the components of
254 the given \a margins by the given \a divisor.
255
256 \sa QMargins::operator*=(), QMargins::operator/=()
257
258 \since 5.1
259*/
260
261/*!
262 \fn QMargins operator+(const QMargins &margins)
263 \relates QMargins
264
265 Returns a QMargin object that is formed from all components of \a margins.
266
267 \since 5.3
268*/
269
270/*!
271 \fn QMargins operator-(const QMargins &margins)
272 \relates QMargins
273
274 Returns a QMargin object that is formed by negating all components of \a margins.
275
276 \since 5.1
277*/
278
279/*!
280 \fn QMargins operator|(const QMargins &m1, const QMargins &m2)
281 \relates QMargins
282
283 Returns a QMargins object that is formed from the maximum of each
284 component of \a m2 and \a m1.
285
286 \sa QMargins::operator+=(), QMargins::operator-=()
287
288 \since 6.0
289*/
290
291/*!
292 \fn QMargins &QMargins::operator+=(const QMargins &margins)
293
294 Add each component of \a margins to the respective component of this object
295 and returns a reference to it.
296
297 \sa operator-=()
298
299 \since 5.1
300*/
301
302/*!
303 \fn QMargins &QMargins::operator-=(const QMargins &margins)
304
305 Subtract each component of \a margins from the respective component of this object
306 and returns a reference to it.
307
308 \sa operator+=()
309
310 \since 5.1
311*/
312
313/*!
314 \fn QMargins &QMargins::operator+=(int addend)
315 \overload
316
317 Adds the \a addend to each component of this object
318 and returns a reference to it.
319
320 \sa operator-=()
321*/
322
323/*!
324 \fn QMargins &QMargins::operator-=(int subtrahend)
325 \overload
326
327 Subtracts the \a subtrahend from each component of this object
328 and returns a reference to it.
329
330 \sa operator+=()
331*/
332
333/*!
334 \fn QMargins &QMargins::operator*=(int factor)
335
336 Multiplies each component of this object by \a factor
337 and returns a reference to it.
338
339 \sa operator/=()
340
341 \since 5.1
342*/
343
344/*!
345 \fn QMargins &QMargins::operator*=(qreal factor)
346 \overload
347
348 Multiplies each component of this object by \a factor
349 and returns a reference to it.
350
351 \sa operator/=()
352
353 \since 5.1
354*/
355
356/*!
357 \fn QMargins &QMargins::operator/=(int divisor)
358
359 Divides each component of this object by \a divisor
360 and returns a reference to it.
361
362 \sa operator*=()
363
364 \since 5.1
365*/
366
367/*!
368 \fn QMargins &QMargins::operator/=(qreal divisor)
369
370 \overload
371
372 \sa operator*=()
373
374 \since 5.1
375*/
376
377/*!
378 \fn QMargins::toMarginsF() const
379 \since 6.4
380
381 Returns these margins as margins with floating point accuracy.
382
383 \sa QMarginsF::toMargins()
384*/
385
386/*****************************************************************************
387 QMargins stream functions
388 *****************************************************************************/
389#ifndef QT_NO_DATASTREAM
390/*!
391 \fn QDataStream &operator<<(QDataStream &stream, const QMargins &m)
392 \relates QMargins
393
394 Writes margin \a m to the given \a stream and returns a
395 reference to the stream.
396
397 \sa {Serializing Qt Data Types}
398*/
399
400QDataStream &operator<<(QDataStream &s, const QMargins &m)
401{
402 s << m.left() << m.top() << m.right() << m.bottom();
403 return s;
404}
405
406/*!
407 \fn QDataStream &operator>>(QDataStream &stream, QMargins &m)
408 \relates QMargins
409
410 Reads a margin from the given \a stream into margin \a m
411 and returns a reference to the stream.
412
413 \sa {Serializing Qt Data Types}
414*/
415
416QDataStream &operator>>(QDataStream &s, QMargins &m)
417{
418 int left, top, right, bottom;
419 s >> left; m.setLeft(left);
420 s >> top; m.setTop(top);
421 s >> right; m.setRight(right);
422 s >> bottom; m.setBottom(bottom);
423 return s;
424}
425#endif // QT_NO_DATASTREAM
426
427#ifndef QT_NO_DEBUG_STREAM
428QDebug operator<<(QDebug dbg, const QMargins &m)
429{
430 QDebugStateSaver saver(dbg);
431 dbg.nospace();
432 dbg << "QMargins" << '(';
433 QtDebugUtils::formatQMargins(debug&: dbg, margins: m);
434 dbg << ')';
435 return dbg;
436}
437#endif
438
439/*!
440 \class QMarginsF
441 \inmodule QtCore
442 \ingroup painting
443 \since 5.3
444
445 \compares equality
446 \compareswith equality QMargins
447 \endcompareswith
448
449 \brief The QMarginsF class defines the four margins of a rectangle.
450
451 QMarginsF defines a set of four margins; left, top, right, and bottom,
452 that describe the finite size of the borders surrounding a rectangle.
453
454 The isNull() function returns \c true only if all margins are very close to zero.
455
456 QMarginsF objects can be streamed as well as compared.
457*/
458
459
460/*****************************************************************************
461 QMarginsF member functions
462 *****************************************************************************/
463
464/*!
465 \fn QMarginsF::QMarginsF()
466
467 Constructs a margins object with all margins set to 0.
468
469 \sa isNull()
470*/
471
472/*!
473 \fn QMarginsF::QMarginsF(qreal left, qreal top, qreal right, qreal bottom)
474
475 Constructs margins with the given \a left, \a top, \a right, and \a bottom.
476 All parameters must be finite.
477
478 \sa setLeft(), setRight(), setTop(), setBottom()
479*/
480
481/*!
482 \fn QMarginsF::QMarginsF(const QMargins &margins)
483
484 Constructs margins copied from the given \a margins.
485
486 \sa QMargins::toMarginsF()
487*/
488
489/*!
490 \fn bool QMarginsF::isNull() const
491
492 Returns \c true if all margins are very close to 0; otherwise returns
493 false.
494
495 \sa {<QtNumeric>::}{qFuzzyIsNull()}
496*/
497
498
499/*!
500 \fn qreal QMarginsF::left() const
501
502 Returns the left margin.
503
504 \sa setLeft()
505*/
506
507/*!
508 \fn qreal QMarginsF::top() const
509
510 Returns the top margin.
511
512 \sa setTop()
513*/
514
515/*!
516 \fn qreal QMarginsF::right() const
517
518 Returns the right margin.
519*/
520
521/*!
522 \fn qreal QMarginsF::bottom() const
523
524 Returns the bottom margin.
525*/
526
527
528/*!
529 \fn void QMarginsF::setLeft(qreal aleft)
530
531 Sets the left margin to \a aleft (which must be finite).
532*/
533
534/*!
535 \fn void QMarginsF::setTop(qreal atop)
536
537 Sets the top margin to \a atop (which must be finite).
538*/
539
540/*!
541 \fn void QMarginsF::setRight(qreal aright)
542
543 Sets the right margin to \a aright (which must be finite).
544*/
545
546/*!
547 \fn void QMarginsF::setBottom(qreal abottom)
548
549 Sets the bottom margin to \a abottom (which must be finite).
550*/
551
552/*!
553 \fn bool QMarginsF::operator==(const QMarginsF &lhs, const QMarginsF &rhs)
554
555 Returns \c true if \a lhs and \a rhs are approximately equal; otherwise
556 returns false.
557
558 \warning This function does not check for strict equality; instead,
559 it uses a fuzzy comparison to compare the margins.
560
561 \sa qFuzzyCompare
562*/
563
564/*!
565 \fn bool QMarginsF::operator!=(const QMarginsF &lhs, const QMarginsF &rhs)
566
567 Returns \c true if \a lhs and \a rhs are sufficiently different; otherwise
568 returns \c false.
569
570 \warning This function does not check for strict inequality; instead,
571 it uses a fuzzy comparison to compare the margins.
572
573 \sa qFuzzyCompare
574*/
575
576/*!
577 \fn const QMarginsF operator+(const QMarginsF &lhs, const QMarginsF &rhs)
578 \relates QMarginsF
579
580 Returns a QMarginsF object that is the sum of the given margins, \a lhs
581 and \a rhs; each component is added separately.
582
583 \sa QMarginsF::operator+=(), QMarginsF::operator-=()
584*/
585
586/*!
587 \fn const QMarginsF operator-(const QMarginsF &lhs, const QMarginsF &rhs)
588 \relates QMarginsF
589
590 Returns a QMarginsF object that is formed by subtracting \a rhs from
591 \a lhs; each component is subtracted separately.
592
593 \sa QMarginsF::operator+=(), QMarginsF::operator-=()
594*/
595
596/*!
597 \fn const QMarginsF operator+(const QMarginsF &lhs, qreal rhs)
598 \relates QMarginsF
599
600 Returns a QMarginsF object that is formed by adding \a rhs (which must be
601 finite) to each component of \a lhs.
602
603 \sa QMarginsF::operator+=(), QMarginsF::operator-=()
604*/
605
606/*!
607 \fn const QMarginsF operator+(qreal lhs, const QMarginsF &rhs)
608 \relates QMarginsF
609
610 Returns a QMarginsF object that is formed by adding \a lhs (which must be
611 finite) to each component of \a rhs.
612
613 \sa QMarginsF::operator+=(), QMarginsF::operator-=()
614*/
615
616/*!
617 \fn const QMarginsF operator-(const QMarginsF &lhs, qreal rhs)
618 \relates QMarginsF
619
620 Returns a QMarginsF object that is formed by subtracting \a rhs (which must
621 be finite) from each component of \a lhs.
622
623 \sa QMarginsF::operator+=(), QMarginsF::operator-=()
624*/
625
626/*!
627 \fn const QMarginsF operator*(const QMarginsF &lhs, qreal rhs)
628 \relates QMarginsF
629 \overload
630
631 Returns a QMarginsF object that is formed by multiplying each component
632 of the given \a lhs margins by finite factor \a rhs.
633
634 \sa QMarginsF::operator*=(), QMarginsF::operator/=()
635*/
636
637/*!
638 \fn const QMarginsF operator*(qreal lhs, const QMarginsF &rhs)
639 \relates QMarginsF
640 \overload
641
642 Returns a QMarginsF object that is formed by multiplying each component
643 of the given \a lhs margins by finite factor \a rhs.
644
645 \sa QMarginsF::operator*=(), QMarginsF::operator/=()
646*/
647
648/*!
649 \fn const QMarginsF operator/(const QMarginsF &lhs, qreal rhs)
650 \relates QMarginsF
651 \overload
652
653 Returns a QMarginsF object that is formed by dividing the components of
654 the given \a lhs margins by the given \a rhs divisor.
655
656 The divisor must not be either zero or NaN.
657
658 \sa QMarginsF::operator*=(), QMarginsF::operator/=()
659*/
660
661/*!
662 \fn QMarginsF operator|(const QMarginsF &m1, const QMarginsF &m2)
663 \relates QMarginsF
664 \overload
665
666 Returns a QMarginsF object that is formed from the maximum of each
667 component of \a m2 and \a m1.
668
669 \sa QMarginsF::operator+=(), QMarginsF::operator-=()
670
671 \since 6.0
672*/
673
674/*!
675 \fn QMarginsF operator+(const QMarginsF &margins)
676 \relates QMarginsF
677
678 Returns a QMargin object that is formed from all components of \a margins.
679*/
680
681/*!
682 \fn QMarginsF operator-(const QMarginsF &margins)
683 \relates QMarginsF
684
685 Returns a QMargin object that is formed by negating all components of \a margins.
686*/
687
688/*!
689 \fn QMarginsF &QMarginsF::operator+=(const QMarginsF &margins)
690
691 Add each component of \a margins to the respective component of this object
692 and returns a reference to it.
693
694 \sa operator-=()
695*/
696
697/*!
698 \fn QMarginsF &QMarginsF::operator-=(const QMarginsF &margins)
699
700 Subtract each component of \a margins from the respective component of this object
701 and returns a reference to it.
702
703 \sa operator+=()
704*/
705
706/*!
707 \fn QMarginsF &QMarginsF::operator+=(qreal addend)
708 \overload
709
710 Adds the given finite \a addend to each component of this object
711 and returns a reference to it.
712
713 \sa operator-=()
714*/
715
716/*!
717 \fn QMarginsF &QMarginsF::operator-=(qreal subtrahend)
718 \overload
719
720 Subtracts the given finite \a subtrahend from each component of this object
721 and returns a reference to it.
722
723 \sa operator+=()
724*/
725
726/*!
727 \fn QMarginsF &QMarginsF::operator*=(qreal factor)
728
729 Multiplies each component of this object by the given finite \a factor
730 and returns a reference to this object.
731
732 \sa operator/=()
733*/
734
735/*!
736 \fn QMarginsF &QMarginsF::operator/=(qreal divisor)
737
738 Divides each component of this object by \a divisor and returns a reference
739 to this object.
740
741 The \a divisor must not be either zero or NaN.
742
743 \sa operator*=()
744*/
745
746/*!
747 \fn QMargins QMarginsF::toMargins() const
748
749 Returns an integer-based copy of this margins object.
750
751 Note that the components in the returned margins will be rounded to
752 the nearest integer.
753
754 \sa QMarginsF(), QMargins::toMarginsF()
755*/
756
757/*!
758 \fn bool QMarginsF::qFuzzyCompare(const QMarginsF &lhs, const QMarginsF &rhs)
759 \since 6.8
760
761 Returns \c true if \a lhs is approximately equal to \a rhs;
762 otherwise returns \c false.
763*/
764
765/*!
766 \fn bool QMarginsF::qFuzzyIsNull(const QMarginsF &margins)
767 \since 6.8
768
769 Returns \c true if all components of margsins \a margins are
770 approximately equal to zero; otherwise returns \c false.
771*/
772
773/*****************************************************************************
774 QMarginsF stream functions
775 *****************************************************************************/
776#ifndef QT_NO_DATASTREAM
777/*!
778 \fn QDataStream &operator<<(QDataStream &stream, const QMarginsF &m)
779 \relates QMarginsF
780
781 Writes margin \a m to the given \a stream and returns a
782 reference to the stream.
783
784 \sa {Serializing Qt Data Types}
785*/
786
787QDataStream &operator<<(QDataStream &s, const QMarginsF &m)
788{
789 s << double(m.left()) << double(m.top()) << double(m.right()) << double(m.bottom());
790 return s;
791}
792
793/*!
794 \fn QDataStream &operator>>(QDataStream &stream, QMarginsF &m)
795 \relates QMarginsF
796
797 Reads a margin from the given \a stream into margin \a m
798 and returns a reference to the stream.
799
800 \sa {Serializing Qt Data Types}
801*/
802
803QDataStream &operator>>(QDataStream &s, QMarginsF &m)
804{
805 double left, top, right, bottom;
806 s >> left;
807 s >> top;
808 s >> right;
809 s >> bottom;
810 m = QMarginsF(qreal(left), qreal(top), qreal(right), qreal(bottom));
811 return s;
812}
813#endif // QT_NO_DATASTREAM
814
815#ifndef QT_NO_DEBUG_STREAM
816QDebug operator<<(QDebug dbg, const QMarginsF &m)
817{
818 QDebugStateSaver saver(dbg);
819 dbg.nospace();
820 dbg << "QMarginsF" << '(';
821 QtDebugUtils::formatQMargins(debug&: dbg, margins: m);
822 dbg << ')';
823 return dbg;
824}
825#endif
826
827QT_END_NAMESPACE
828

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