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