/*
 * 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
*/