a8081885d2
This version generates some warnings and identified some problems in our documentation. It is also a bit more vigilant about undocumented elements, so these are now decorated with a brief description. In the BNotification docs I used a stray \p to create some whitespace between code and an image. This is now fixed in the CSS instead.
450 lines
9.0 KiB
Plaintext
450 lines
9.0 KiB
Plaintext
/*
|
|
* Copyright 2014 Haiku, Inc. All rights reserved.
|
|
* Distributed under the terms of the MIT License.
|
|
*
|
|
* Authors:
|
|
* Stephan Aßmus, superstippi@gmx.de
|
|
* Stefano Ceccherini, burton666@libero.it
|
|
* John Scipione, jscipione@gmail.com
|
|
*
|
|
* Corresponds to:
|
|
* headers/os/interface/Region.h hrev47312
|
|
* src/kits/interface/Region.cpp hrev47312
|
|
*/
|
|
|
|
|
|
/*!
|
|
\file Region.h
|
|
\ingroup interface
|
|
\ingroup libbe
|
|
\brief BRegion class definition.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\class BRegion
|
|
\ingroup interface
|
|
\ingroup libbe
|
|
\brief An area composed of rectangles.
|
|
|
|
The rectangles do not need to overlap. This class is useful for creating
|
|
clipping masks.
|
|
|
|
\warning BRegion is designed to be used with integral coordinates only.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BRegion::BRegion()
|
|
\brief Initializes an empty region. The region contains no rectangles,
|
|
and its bounds are invalid.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BRegion::BRegion(const BRegion& other)
|
|
\brief Initializes a region as a copy of \a other.
|
|
|
|
\param other The region to copy.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BRegion::BRegion(const BRect rect)
|
|
\brief Initializes a region to contain a \a rect.
|
|
|
|
\param rect The BRect to add to the region.
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BRegion::BRegion(const clipping_rect& clipping)
|
|
\brief Initializes a region to contain a clipping_rect.
|
|
|
|
\param clipping The clipping_rect to set the region to, already in
|
|
internal rect format.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BRegion::~BRegion()
|
|
\brief Destroys the BRegion freeing any memory allocated by it.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\name Operators
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn BRegion& BRegion::operator=(const BRegion& other)
|
|
\brief Modifies the BRegion to be a copy of \a other.
|
|
|
|
\param other the BRegion to copy.
|
|
|
|
\return This method always returns \c *this.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BRegion::operator==(const BRegion& other) const
|
|
\brief Compares this region to \a other by value.
|
|
|
|
\param other the BRegion to compare to.
|
|
|
|
\return \c true if the regions are the same, \c false otherwise.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\fn void BRegion::Set(BRect rect)
|
|
\brief Set the region to bounds of \a newBounds.
|
|
|
|
\param rect The BRect to set the bounds to.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BRegion::Set(clipping_rect clipping)
|
|
\brief Set the region to the bounds of \a clipping_rect.
|
|
|
|
\param clipping The clipping_rect to set the bounds to.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BRect BRegion::Frame() const
|
|
\brief Returns a rectangle that encloses the BRegion.
|
|
|
|
\return A BRect that encloses the BRegion.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn clipping_rect BRegion::FrameInt() const
|
|
\brief Returns the bounds of the region as a clipping_rect
|
|
(which has integer coordinates).
|
|
|
|
\return The clipping_rect which represents the region's bounds.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BRect BRegion::RectAt(int32 index)
|
|
\brief Returns the rectangle contained in the region at the given \a index.
|
|
|
|
\param index The index of the BRect to retreive.
|
|
|
|
\return If the given index is valid, it returns the BRect at that index,
|
|
otherwise, it returns an invalid BRect.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BRect BRegion::RectAt(int32 index) const
|
|
\brief Returns the rectangle contained in the region at the given \a index.
|
|
|
|
\param index The index of the BRect to retreive. (zero based)
|
|
|
|
\return If the given index is valid, it returns the BRect at that index,
|
|
otherwise, it returns an invalid BRect.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn clipping_rect BRegion::RectAtInt(int32 index)
|
|
\brief Returns the clipping_rect contained in the region at the given
|
|
\a index.
|
|
|
|
\param index The index of the clipping_rect to retrieve. (zero based)
|
|
|
|
\return If the given index is valid, it returns the clipping_rect at that
|
|
index, otherwise, it returns an invalid clipping_rect.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn clipping_rect BRegion::RectAtInt(int32 index) const
|
|
\brief Returns the clipping_rect contained in the region at the given
|
|
\a index.
|
|
|
|
\param index The index of the clipping_rect to retrieve. (zero based)
|
|
|
|
\return If the given index is valid, it returns the clipping_rect at that
|
|
index, otherwise, it returns an invalid clipping_rect.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int32 BRegion::CountRects()
|
|
\brief Returns the number of rectangles contained in the region.
|
|
|
|
\return The number of rectangles in the region as an int32.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn int32 BRegion::CountRects() const
|
|
\brief Returns the number of rectangles contained in the region.
|
|
|
|
\return The number of rectangles in the region as an int32.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BRegion::Intersects(BRect rect) const
|
|
\brief Returns whether or not the region has any area in common with
|
|
\a rect.
|
|
|
|
\param rect The BRect to check the region against.
|
|
|
|
\return \c true if the region has any area in common with the BRect,
|
|
\c false if not.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BRegion::Intersects(clipping_rect clipping) const
|
|
\brief Returns whether or not the region has any area in common with
|
|
\a clipping.
|
|
|
|
\param clipping The clipping_rect to check the region against.
|
|
|
|
\return \c true if the region has any area in common with the
|
|
clipping_rect, \c false if not.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BRegion::Contains(BPoint point) const
|
|
\brief Returns whether or not if the region contains the given \a point.
|
|
|
|
\param point The \a point to check.
|
|
|
|
\return \c true if the region contains the \a point, \c false if not.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BRegion::Contains(int32 x, int32 y)
|
|
\brief Returns whether or not the region contains the given coordinates.
|
|
|
|
\param x The \c x coordinate of the point to check.
|
|
\param y The \c y coordinate of the point to check.
|
|
|
|
\return \c true if the region contains the point, \c false if not.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BRegion::Contains(int32 x, int32 y) const
|
|
\brief Return whether or not the region contains the given coordinates.
|
|
|
|
\param x The \c x coordinate of the point to check.
|
|
\param y The \c y coordinate of the point to check.
|
|
|
|
\return \c true if the region contains the point, \c false if not.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BRegion::PrintToStream() const
|
|
\brief Prints each rect in the the BRegion to standard output.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BRegion::OffsetBy(const BPoint& point)
|
|
\brief Applies the given offsets given by the x and y coordinates of
|
|
\a point to each rectangle contained in the region and recalculates
|
|
the region's bounds.
|
|
|
|
\param point The point to get the coordinates to offset by.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BRegion::OffsetBy(int32 x, int32 y)
|
|
\brief Applies the given \a x and \a y offsets to each rectangle contained
|
|
in the region and recalculates the region's bounds.
|
|
|
|
\param x The horizontal offset.
|
|
\param y The vertical offset.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BRegion::ScaleBy(BSize scale)
|
|
\brief Resize each of the contained rectangles by the given factor
|
|
and recalculates the region's bounds.
|
|
|
|
\param scale The scale factor
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BRegion::ScaleBy(float x, float y)
|
|
\brief Resize each of the contained rectangles by the given factors
|
|
and recalculates the region's bounds.
|
|
|
|
\param x The horizontal scale.
|
|
\param y The vertical scale.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BRegion::MakeEmpty()
|
|
\brief Empties the region so that it doesn't containt any rects, and
|
|
invalidates its bounds.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BRegion::Include(BRect rect)
|
|
\brief Modifies the region so that it includes the given \a rect.
|
|
|
|
\param rect The BRect to include in the region.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BRegion::Include(clipping_rect clipping)
|
|
\brief Modifies the region so that it includes the given \a clipping
|
|
rectangle.
|
|
|
|
\param clipping The clipping_rect to include in the region.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BRegion::Include(const BRegion* region)
|
|
\brief Modifies the region to include the area of the given \a region.
|
|
|
|
\param region The \a region to be included.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BRegion::Exclude(BRect rect)
|
|
\brief Modifies the region excluding the area of the given \a rect.
|
|
|
|
\param rect The BRect to be excluded.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BRegion::Exclude(clipping_rect clipping)
|
|
\brief Modifies the region excluding the area of the given \a clipping
|
|
rectangle.
|
|
|
|
\param clipping The clipping_rect to be excluded.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BRegion::Exclude(const BRegion* region)
|
|
\brief Modifies the region excluding the area contained by the given
|
|
\a region.
|
|
|
|
\param region The BRegion to be excluded.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BRegion::IntersectWith(const BRegion* region)
|
|
\brief Modifies the region, so that it will contain only the area
|
|
in common with \a region.
|
|
|
|
\param region the BRegion to intersect with.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BRegion::ExclusiveInclude(const BRegion* region)
|
|
\brief Modifies the region so that it contains only the area
|
|
which the BRegion and \a region do NOT have in common.
|
|
|
|
\param region the BRegion to exclusively include.
|
|
|
|
\since Haiku R1
|
|
*/
|