diff --git a/core/area.h b/core/area.h --- a/core/area.h +++ b/core/area.h @@ -33,23 +33,42 @@ /** * NormalizedPoint is a helper class which stores the coordinates * of a normalized point. Normalized means that the coordinates are - * between 0 and 1 so that it is page size independent. + * between 0 and 1, independent of the page size. * - * Example: - * The normalized point is (0.5, 0.3) + * @par Coordinate System + * * Left edge of the page: x = 0 + * * Right edge of the page: x = 1 + * * Top edge of the page: y = 0 + * * Bottom edge of the page: y = 1 * - * If you want to draw it on a 800x600 page, just multiply the x coordinate (0.5) with - * the page width (800) and the y coordinate (0.3) with the page height (600), so - * the point will be drawn on the page at (400, 180). + * @par Example + * The normalized point is (0.5, 0.3) * - * That allows you to zoom the page by just multiplying the normalized points with the - * zoomed page size. + * If you want to draw it on a 800x600 page, + * just multiply the x coordinate (0.5) with the page width (800), + * and the y coordinate (0.3) with the page height (600). + * So, the point will be drawn on the page at (400, 180). + * + * That allows you to zoom the page by just multiplying the normalized points with the + * zoomed page size. + * + * NormalizedPoint is also useful for describing the position of mouse click events on a page. + * + * @par Geometric operations + * NormalizedPoint supports basic geometric operations. + * * You can transform it with a QTransform matrix. + * * With a given page size, you can calculate the squared absolute distance to another + * NormalizedPoint or a line of two NormalizedPoints. + * + * NormalizedRect provides additional geometric operations recarding rectangles. + * + * @see NormalizedRect */ class OKULARCORE_EXPORT NormalizedPoint { public: /** - * Creates a new empty normalized point. + * Creates a normalized point at (0, 0). */ NormalizedPoint(); @@ -59,8 +78,8 @@ NormalizedPoint( double x, double y ); /** - * Creates a new normalized point with the coordinates (@p x, @p y) which are normalized - * by the scaling factors @p xScale and @p yScale. + * Creates a new normalized point from an absolute point (@p x, @p y) + * on a page of size @p xScale x @p yScale. */ NormalizedPoint( int x, int y, int xScale, int yScale ); @@ -78,14 +97,14 @@ void transform( const QTransform &matrix ); /** - * Returns squared distance to point @p x @p y @p xScale @p yScale + * Returns squared distance to normalized point (@p x, @p y) at a page size of @p xScale x @p yScale. * @since 0.17 (KDE 4.11) */ double distanceSqr( double x, double y, double xScale, double yScale ) const; - /** - * @brief Calculates distance of the point @p x @p y @p xScale @p yScale to the line segment from @p start to @p end + * @brief Returns squared distance of the normalized point (@p x, @p y) + * to the line segment from @p start to @p end at a page size of @p xScale x @p yScale. * @since 0.17 (KDE 4.11) */ static double distanceSqr( double x, double y, double xScale, double yScale, const NormalizedPoint& start, const NormalizedPoint& end ); @@ -103,8 +122,18 @@ /** - * NormalizedRect is a helper class which stores the coordinates - * of a normalized rect, which is a rectangle of @see NormalizedPoints. + * A NormalizedRect is a rectangle which can be defined by two NormalizedPoints. + * + * It describes a rectangular area on a page, independent of the page size or zoom. + * Like NormalizedPoint, it can be scaled to absolute page sizes. + * + * Currently, NormalizedRect is used to describe bounding boxes of TextEntity objects, + * and the highlight area of text selections. + * + * RegularAreaRect is a list of NormalizedRects, so more complex shapes can be described, + * also independent of the page size or zoom. + * + * @see NormalizedPoint, RegularAreaRect, TextEntity */ class OKULARCORE_EXPORT NormalizedRect { @@ -126,12 +155,19 @@ * @li y = top * @li width = right - left * @li height = bottom - top + * + * @note + * The coordinates for @p left and @p top must be lower than + * @p right and @p bottom, respectively, to avoid negative width or height. */ NormalizedRect( double left, double top, double right, double bottom ); /** - * Creates a normalized rectangle of the given @p rectangle which is normalized - * by the scaling factors @p xScale and @p yScale. + * Creates a normalized rectangle of the given @p rectangle at a + * page size of @p xScale x @p yScale. + * + * @note + * The rectangle must be QRect::normalize()-d, i. e. width and height must be positive. */ NormalizedRect( const QRect &rectangle, double xScale, double yScale ); @@ -148,7 +184,7 @@ ~NormalizedRect(); /** - * Build a normalized rect from a QRectF. + * Build a normalized rect from a QRectF, which already has normalized coordinates. */ static NormalizedRect fromQRectF( const QRectF &rect ); @@ -158,8 +194,8 @@ bool isNull() const; /** - * Returns whether the normalized rectangle contains the normalized coordinates - * @p x and @p y. + * Returns whether the normalized rectangle contains the normalized point + * (@p x, @p y). */ bool contains( double x, double y ) const; @@ -189,6 +225,7 @@ /** * Same functionality as geometry, but the output is now rounded before typecasting to int + * * @since 0.14 (KDE 4.8) */ QRect roundedGeometry( int xScale, int yScale ) const; @@ -207,7 +244,7 @@ /** * Returns the intersection of this normalized rectangle with the specified - * @p other. If the rects do not intersect then the result is null. + * @p other. If the rects do not intersect then the result is a null rectangle. * * @since 0.7 (KDE 4.1) */ @@ -231,62 +268,63 @@ void transform( const QTransform &matrix ); /** - * Returns true if the point pt is located to the bottom of the rectangle + * Returns true if the point @p pt is located below the bottom of the rectangle * @since 0.14 (KDE 4.8) */ bool isBottom(const NormalizedPoint& pt) const { return bottom < pt.y; } /** - * Returns true if the point pt is located on the top of the rectangle + * Returns true if the point @p pt is located above the top of the rectangle * @since 0.14 (KDE 4.8) */ bool isTop(const NormalizedPoint& pt) const { return top > pt.y; } /** - * Returns true if the point pt is located under the top of the rectangle + * Returns true if the point @p pt is located below the top of the rectangle * @since 0.14 (KDE 4.8) */ bool isBottomOrLevel(const NormalizedPoint& pt) const { return top < pt.y; } /** - * Returns true if the point pt is located above the bottom of the rectangle + * Returns true if the point @p pt is located above the bottom of the rectangle * @since 0.14 (KDE 4.8) */ bool isTopOrLevel(const NormalizedPoint& pt) const { return bottom > pt.y; } /** - * Returns true if the point pt is located to the right of the left arm of rectangle + * Returns true if the point @p pt is located to the right of the left edge of the rectangle * @since 0.14 (KDE 4.8) */ bool isLeft(const NormalizedPoint& pt) const { return left < pt.x; } /** - * Returns true if the point pt is located to the left of the right arm of rectangle + * Returns true if the point @p pt is located to the left of the right edge of the rectangle * @since 0.14 (KDE 4.8) */ bool isRight(const NormalizedPoint& pt) const { return right > pt.x; } /** - * Returns the distance of the point @p x @p y @p xScale @p yScale to the closest - * edge or 0 if the point is within the rectangle + * Returns the squared distance of the normalized point (@p x, @p y) + * at a page size of @p xScale x @p yScale + * to the closest edge, or 0 if the point is within the rectangle. * @since 0.17 (KDE 4.11) */ double distanceSqr(double x, double y, double xScale, double yScale) const @@ -417,8 +455,8 @@ virtual QRect boundingRect( double xScale, double yScale ) const; /** - * Returns whether the object rectangle contains the point @p x, @p y for the - * scaling factor @p xScale and @p yScale. + * Returns whether the object rectangle contains the point with absolute coordinates + * (@p x, @p y) at a page size of @p xScale x @p yScale. */ virtual bool contains( double x, double y, double xScale, double yScale ) const; @@ -428,8 +466,10 @@ virtual void transform( const QTransform &matrix ); /** - * Returns the square of the distance between the object and the point @p x, @p y - * for the scaling factor @p xScale and @p yScale. + * Returns the squared distance between the object + * and the point with + * normalized coordinates (@p x, @p y) + * at a page size of @p xScale x @p yScale. * * @since 0.8.2 (KDE 4.2.2) */ @@ -547,14 +587,20 @@ /// @endcond /** - * @short A regular area of NormalizedShape which normalizes a Shape + * @short An area on a page, which consists of multiple NormalizedShapes. + * + * This is a template class to describe an area which consists of multiple shapes of the same type, + * intersecting or non-intersecting. + * The coordinates are normalized, and can be converted to absolute coordinates with a given page size. * * Class NormalizedShape \b must have the following functions/operators defined: - * - bool contains( double, double ) + * - bool contains( double, double ), whether it contains the given NormalizedPoint * - bool intersects( NormalizedShape ) * - bool isNull() - * - Shape geometry( int, int ) - * - operator|=( NormalizedShape ) which unite two NormalizedShape's + * - Shape geometry( int, int ), which converts to absolute coordinates + * - operator|=( NormalizedShape ), which unites two NormalizedShape's + * + * @see RegularAreaRect */ template class RegularArea : public QList { @@ -819,6 +865,16 @@ givePtr( (*this)[i] )->transform( matrix ); } +/** + * This is a list of NormalizedRect, to describe an area consisting of multiple rectangles on a page. + * + * This can be used e. g. to describe a text highlight area, + * which consists of multiple, intersecting or non-intersecting rectangles. + * + * Given a page size, the area can be converted to a list of QRects with absolute coordinates. + * + * @see NormalizedRect + */ class OKULARCORE_EXPORT RegularAreaRect : public RegularArea< NormalizedRect, QRect > { public: