File indexing completed on 2024-05-12 04:20:36

 /*
  * SPDX-FileCopyrightText: 2001-2015 Klaralvdalens Datakonsult AB. All rights reserved.
  *
  * This file is part of the KD Chart library.
  *
  * SPDX-License-Identifier: GPL-2.0-or-later
  */
 
 #ifndef KCHARTRELATIVEPOSITION_H
 #define KCHARTRELATIVEPOSITION_H
 
 #include <QDebug>
 #include <QMetaType>
 #include <Qt>
 #include <QPointF>
 #include <QSizeF>
 #include "KChartGlobal.h"
 
 namespace KChart {
 
     class Position;
     class PositionPoints;
     class Measure;
 
 /**
   \class RelativePosition KChartRelativePosition.h
   \brief Defines relative position information: reference area, position
   in this area (reference position), horizontal / vertical padding, and rotation.
 
   See detailed description of \a KChart::Position for an illustration of the
   different possible reference positions.
 
   Using RelativePosition you can specify the relative parts
   of some position information, and you can specify the absolute parts:
   the reference area, and the position in this area.
 
   \note To get an absolute position, you have three options:
   \li either you declare both, the relative and the absolute parts,
       using setReferenceArea for the latter,
   \li or you specify a set of points, using setReferencePoints,
   \li or you don't use either, leaving it to KChart to find a suitable reference area.
   */
 class KCHART_EXPORT RelativePosition
 {
 public:
     RelativePosition();
     RelativePosition( const RelativePosition& );
 
     RelativePosition & operator=( const RelativePosition & other );
 
     ~RelativePosition();
 
     /**
      * \brief Set the reference area to be used to find the anchor point.
      *
      * The reference area's type can be either a QWidget subclass or a KChart::AbstractArea subclass.
      *
      * \note Usage of reference area and reference points is mutually exclusive:
      * Only one can be used, so any previously set reference points are cleared
      * when you call setReferenceArea.
      *
      * Also note: In a few cases KChart will ignore your area (or points, resp.) settings!
      * Relative positioning of data value texts is an example: For these
      * the reference area is always taken to be the data area.
      *
      * \sa setReferencePosition, setAlignment, setHorizontalPadding, setVerticalPadding
      */
     void setReferenceArea( QObject* area );
     QObject* referenceArea() const;
 
     /**
      * \brief Set a set of points from which the anchor point will be selected.
      *
      * \note Usage of reference area and reference points is mutually exclusive:
      * Only one can be used, so any previously set reference area is cleared
      * when you call setReferencePoints.
      *
      * Also note: In a few cases KChart will ignore your points (or area, resp.) settings!
      * Relative positioning of data value texts is an example: For these
      * the reference area is always taken to be the data area.
      *
      * \sa setReferenceArea, setReferencePosition, setAlignment, setHorizontalPadding, setVerticalPadding
      */
     void setReferencePoints( const PositionPoints& points );
     const PositionPoints referencePoints() const;
 
     /**
      * \brief Set the position of the anchor point.
      *
      * The anchor point of a RelativePosition may be one of the pre-defined
      * points of it's reference area - for details see KChart::Position.
      *
      * See detailed description of \a KChart::Position for an illustration of the
      * different possible reference positions.
      *
      *  \sa resetReferencePosition, setReferenceArea, setAlignment, setHorizontalPadding, setVerticalPadding, KChart::Position
      */
     void setReferencePosition( Position position );
 
     /**
      * \brief Resets the position of the anchor point to the built-in default.
      *
      * If the anchor point of a RelativePosition is reset (or never changed from the
      * default setting) KChart will choose an appropriate Position at run-time.
      *
      * e.g. BarDiagrams will use Position::North / Position::South for positive / negative values.
      *
      *  \sa setReferencePosition, setReferenceArea, setAlignment, setHorizontalPadding, setVerticalPadding, KChart::Position
      */
     void resetReferencePosition();
     Position referencePosition() const;
 
     /**
      * Set the alignment of the content placed by this RelativePosition.
      *
      * Padding is applied first to obtain the final reference point
      * for the content's alignment
      *
      * \note To print centered content, besides calling setAlignment( Qt::AlignCenter )
      * you might also want to set zero padding to have your text centered more precisely.
      *
      * \sa setReferencePosition, setReferenceArea, setHorizontalPadding, setVerticalPadding
      */
     void setAlignment( Qt::Alignment flags );
     Qt::Alignment alignment() const;
 
     /**
      * Set the width of the horizontal padding between the anchor point and the content
      * placed by this RelativePosition.
      *
      * \note When printing data value texts this Measure is used to find the alignment
      * point for this text, then alignment() is use to determine how to align the text
      * relative to that point.
      * The font height is used as reference size for both horizontal and vertical padding
      * if the respective padding's Measure is using automatic reference area detection.
      *
      * \sa setVerticalPadding, setReferencePosition, setReferenceArea
      */
     void setHorizontalPadding( const Measure& padding );
     Measure horizontalPadding() const;
 
     /**
      * Set the height of the vertical padding between the anchor point and the content
      * placed by this RelativePosition.
      *
      * \note When printing data value texts this Measure is used to find the alignment
      * point for this text, then alignment() is use to determine how to align the text
      * relative to that point.
      * The font height is used as reference size for both horizontal and vertical padding
      * if the respective padding's Measure is using automatic reference area detection.
      *
      * \sa setHorizontalPadding, setReferencePosition, setReferenceArea
      */
     void setVerticalPadding( const Measure& padding );
     Measure verticalPadding() const;
 
     void setRotation( qreal rot );
     qreal rotation() const;
 
     /**
      * \brief Return the reference point, according to the reference area/position, and ignoring padding.
      *
      * This method is called at drawing time.
      * The returned point is used to test if the label of a data value is to be printed: a label
      * is printed only if its reference point is inside or touching the coordinate plane.
      *
      * If polarDegrees is set, the degree information will be returned that was stored for the
      * respective point. This is used by the PieDiagram class to determine how vertical/horizontal
      * padding settings should affect the position of the data value texts' reference points.
      * \sa calculatedPoint, setReferenceArea, setReferencePosition, setHorizontalPadding, setVerticalPadding
      */
     const QPointF referencePoint(qreal* polarDegrees = nullptr) const;
 
     /**
      * \brief Calculate a point, accordin to the reference area/position and the padding.
      *
      * This method is called at drawing time: The returned point is used as anchor point.
      * Note that it is the task of the calling code to place the content, taking the alignment
      * property into account. This class does not know the size of the content so it
      * cannot place it.
      *
      * \sa referencePoint, setReferenceArea, setReferencePosition, setHorizontalPadding, setVerticalPadding
      */
     const QPointF calculatedPoint( const QSizeF& autoSize ) const;
 
     bool operator==( const RelativePosition& ) const;
     bool operator!=( const RelativePosition & other ) const;
 
 private:
     KCHART_DECLARE_PRIVATE_BASE_VALUE( RelativePosition )
 };
 
 inline bool RelativePosition::operator!=( const RelativePosition & other ) const { return !operator==( other ); }
 }
 
 #if !defined(QT_NO_DEBUG_STREAM)
 KCHART_EXPORT QDebug operator<<(QDebug, const KChart::RelativePosition& );
 #endif /* QT_NO_DEBUG_STREAM */
 
 KCHART_DECLARE_SWAP_SPECIALISATION( KChart::RelativePosition )
 
 QT_BEGIN_NAMESPACE
 Q_DECLARE_TYPEINFO( KChart::RelativePosition, Q_MOVABLE_TYPE );
 QT_END_NAMESPACE
 
 Q_DECLARE_METATYPE( KChart::RelativePosition )
 
 #endif // KCHARTRELATIVEPOSITION_H