xref: /haiku/docs/user/interface/Shape.dox (revision a8081885d2bcc5076d27ea1cbc5b9c0cc60f1126)

/*
 * Copyright 2003-2014 Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Marc Flerackers, mflerackers@androme.be
 *		John Scipione, jscipione@gmail.com
 *
 * Corresponds to:
 *		headers/os/interface/Shape.h	 hrev47496
 *		src/kits/interface/Shape.cpp	 hrev47496
 */


/*!
	\file Shape.h
	\ingroup interface
	\ingroup libbe
	\brief BShape and BShapeIterator class definitions.
*/


/*!
	\class BShapeIterator
	\ingroup interface
	\ingroup libbe
	\brief Allows you to iterate through BShape operations.

	You should override this class and implement the IterateMoveTo(),
	IterateLineTo(), IterateBezierTo(), IterateClose(), and IterateArcTo()
	methods which correspond to BShape::MoveTo(), BShape::LineTo(),
	BShape::BezierTo(), BShape::Close() and BShape::ArcTo() respectively.

	\sa BShape

	\since BeOS R4
*/


/*!
	\fn BShapeIterator::BShapeIterator()
	\brief Constructor, does nothing.

	This method does nothing and should be implemented by derived classes.

	\since BeOS R4
*/


/*!
	\fn BShapeIterator::~BShapeIterator()
	\brief Destructor, does nothing.

	This method does nothing and should be implemented by derived classes.

	\since BeOS R4
*/


/*!
	\fn status_t BShapeIterator::Iterate(BShape* shape)
	\brief Iterates over each operation that make up the BShape calling
	       IterateMoveTo(), IterateLineTo(), IterateBezierTo(),
	       IterateClose() or IterateArcTo() depending on the operation.

	\brief shape The BShape object to iterate through.

	\return Always returns \c B_OK. You should override this method
	        to return an appropriate status code.

	\since BeOS R4
*/


/*!
	\fn status_t BShapeIterator::IterateMoveTo(BPoint* point)
	\brief Called by Iterate() to act on \a point.

	This method does nothing and should be implemented by derived classes.

	\param point The point to act on.

	\return Always returns \c B_OK. You should override this method
	        to return an appropriate status code.

	\since BeOS R4
*/


/*!
	\fn status_t BShapeIterator::IterateLineTo(int32 lineCount,
		BPoint* linePoints)
	\brief Called by Iterate() to act on \a lineCount lines comprised of the
	       points specified by \a linePoints.

	This method does nothing and should be implemented by derived classes.

	\param lineCount The number of points in \a linePoints.
	\param linePoints The list of points of lines to act on.

	\return Always returns \c B_OK. You should override this method
	        to return an appropriate status code.

	\since BeOS R4
*/


/*!
	\fn status_t BShapeIterator::IterateBezierTo(int32 bezierCount,
		BPoint* bezierPoints)
	\brief Called by Iterate() to act on \a bezierCount Bézier curves
	       comprised of the points specified by \a bezierPoints.

	This method does nothing and should be implemented by derived classes.

	\param bezierCount The number of points in \a bezierPoints.
	\param bezierPoints The list of Bézier curve points to act on.

	\return Always returns \c B_OK. You should override this method
	        to return an appropriate status code.

	\since BeOS R4
*/


/*!
	\fn status_t BShapeIterator::IterateClose()
	\brief Called by Iterate() to close the BShape.

	This method does nothing and should be implemented by derived classes.

	\return Always returns \c B_OK. You should override this method
	        to return an appropriate status code.

	\since BeOS R4
*/


/*!
	\fn status_t BShapeIterator::IterateArcTo(float& rx, float& ry,
		float& angle, bool largeArc, bool counterClockWise, BPoint& point)
	\brief Called by Iterate() to act on an arc.

	\param rx The horizontal radius of the arc to act on.
	\param ry The vertical radius of the arc to act on.
	\param angle The starting angle of the arc in degrees to act on.
	\param largeArc Whether or not to draw a large arc.
	\param counterClockWise \c true if the arc is drawn counter-clockwise, \c false
	       if the arc is drawn clockwise.
	\param point The center point of the arc to act on.

	This method does nothing and should be implemented by derived classes.

	\return Always returns \c B_OK. You should override this method
	        to return an appropriate status code.

	\since Haiku R1
*/


/*!
	\class BShape
	\ingroup interface
	\ingroup libbe
	\brief Encapsulates a Postscript-style "path".

	You can obtain the outlines of characters from a string as BShape objects
	by calling BFont::GetGlyphShapes().

	\since BeOS R4
*/


/*!
	\fn BShape::BShape()
	\brief Creates an empty BShape object.

	\since BeOS R4
*/


/*!
	\fn BShape::BShape(const BShape& other)
	\brief Creates a new BShape object as a copy of \a other.

	\param other The BShape object to copy from.

	\since BeOS R4
*/


/*!
	\fn BShape::BShape(BMessage* archive)
	\brief Creates a new BShape message from an \a archive message.

	You should call Instantiate() instead as it will validate whether
	or not the object was created successfully.

	\param archive The BMessage object to construct the data from.

	\since BeOS R4
*/


/*!
	\fn BShape::~BShape()
	\brief Destructor, deletes all associated data.

	\since BeOS R4
*/


/*!
	\name Archiving
*/


//! @{


/*!
	\fn status_t BShape::Archive(BMessage* archive, bool deep) const
	\brief Archives the BShape object to a BMessage.

	\param archive The BMessage object to archive the BShape data to.
	\param deep Currently unused.

	\return A status code, \c B_OK on scucess or an error code otherwise.

	\since BeOS R4
*/


/*!
	\fn BArchivable* BShape::Instantiate(BMessage* archive)
	\brief Creates a new BShape object from an \a archive message.

	\param archive The BMessage object to construct the BShape data from.

	\return A new BShape object or \c NULL if \a archive was invalid.

	\since BeOS R4
*/


//! @}


/*!
	\name Operators
*/


//! @{


/*!
	\fn BShape& BShape::operator=(const BShape& other)
	\brief Constructs a BShape object as a copy of \a other by overloading
	       the = operator.

	\param other The BShape object to copy from.

	\brief Always returns *this.

	\since Haiku R1
*/


/*!
	\fn bool BShape::operator==(const BShape& other) const
	\brief Returns whether or not the contents of this BShape and \a other
	       contain the same data.

	\return \c true if the contents are equal, \c false otherwise.

	\since Haiku R1
*/


/*!
	\fn bool BShape::operator!=(const BShape& other) const
	\brief Returns whether or not the contents of this BShape and \a other
	       do NOT contain the same data.

	\return \c true if the contents are NOT equal, \c false otherwise.

	\since Haiku R1
*/


//! @}


/*!
	\fn void BShape::Clear()
	\brief Deletes all data returning the BShape to an empty state.

	\since BeOS R4
*/


/*!
	\fn BRect BShape::Bounds() const
	\brief Returns a BRect that encloses all points in the BShape.

	\warning This implementation doesn't take into account curves at all.

	\since BeOS R4
*/


/*!
	\fn BPoint BShape::CurrentPosition() const
	\brief Returns the current end point of the path.

	\return The current end point of the path or \c B_ORIGIN if no points have
	        been added yet.

	\since Haiku R1
*/


/*!
	\fn status_t BShape::AddShape(const BShape* otherShape)
	\brief Adds the lines and curves of \a otherShape to BShape.

	\return Always returns \c B_OK.

	\since BeOS R4
*/


/*!
	\name Operations
*/


//! @{


/*!
	\fn status_t BShape::MoveTo(BPoint point)
	\brief Adds a "move to" operation to the BShape.

	The next LineTo() or BezierTo() will begin at \a point allowing you to
	create noncontiguous shapes.

	\param point The point to start the next LineTo() or BezierTo() at.

	\return Returns a status code, \c B_OK on success or an error code
	        otherwise.
	\retval B_OK The operation was added successfully.
	\retval B_NO_MEMORY Ran out of memory while trying to add the operation.

	\since BeOS R4
*/


/*!
	\fn status_t BShape::LineTo(BPoint point)
	\brief Adds a "draw line" operation to the BShape.

	A line will be drawn from the previous point to the \a point specified.

	\param point The point to draw a line to starting at the previous location.

	\return Returns a status code, \c B_OK on success or an error code
	        otherwise.
	\retval B_OK The operation was added successfully.
	\retval B_NO_MEMORY Ran out of memory while trying to add the operation.

	\since BeOS R4
*/


/*!
	\fn status_t BShape::BezierTo(BPoint controlPoints[3])
	\brief Adds a "draw Bézier curve" operation to the BShape.

	A Bézier curve is drawn that begins at the current point and is made up
	of the specified \a controlPoints.

	\param controlPoints The points that make up the Bézier curve.

	\return Returns a status code, \c B_OK on success or an error code
	        otherwise.
	\retval B_OK The operation was added successfully.
	\retval B_NO_MEMORY Ran out of memory while trying to add the operation.

	\since BeOS R4
*/


/*!
	\fn status_t BShape::BezierTo(const BPoint& control1,
		const BPoint& control2, const BPoint& endPoint)
	\brief Adds a "draw Bézier curve" operation to the BShape.

	A Bézier curve is drawn that begins at the current point and is made up
	of the specified points.

	\param control1 The first control point of the Bézier curve.
	\param control2 The second control point of the Bézier curve.
	\param endPoint The end point of the Bézier curve.

	\return Returns a status code, \c B_OK on success or an error code
	        otherwise.
	\retval B_OK The operation was added successfully.
	\retval B_NO_MEMORY Ran out of memory while trying to add the operation.

	\since Haiku R1
*/


/*!
	\fn status_t BShape::ArcTo(float rx, float ry, float angle, bool largeArc,
		bool counterClockWise, const BPoint& point)
	\brief Adds a "draw arc" operation to the BShape.

	An arc is draw that begins at the current point and is specified by the
	parameters to this method.

	\param rx The horizontal radius of the arc.
	\param ry The vertical radius of the arc.
	\param angle The starting angle of the arc in degrees.
	\param largeArc Whether or not to draw a large arc.
	\param counterClockWise \c true to draw the arc counter-clockwise, \c false
	       to draw the arc clockwise.
	\param point The center point of the arc.

	\return Returns a status code, \c B_OK on success or an error code
	        otherwise.
	\retval B_OK The operation was added successfully.
	\retval B_NO_MEMORY Ran out of memory while trying to add the operation.

	\since Haiku R1
*/


/*!
	\fn status_t BShape::Close()
	\brief Adds an operation to close the BShape once it is fully constructed.

	\return Returns a status code, \c B_OK on success or an error code
	       otherwise.
	\retval B_OK The operation was added successfully.
	\retval B_NO_MEMORY Ran out of memory while trying to add the operation.

	\since BeOS R4
*/


//! @}