Document BShape and BShapeIterator
This commit is contained in:
John Scipione
parent
db1ef05aef
commit
cb65c3a037
459
docs/user/interface/Shape.dox
Normal file
459
docs/user/interface/Shape.dox
Normal file
@ -0,0 +1,459 @@
|
||||
/*
|
||||
* 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.
|
||||
|
||||
\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
|
||||
*/
|
||||
|
||||
|
||||
//! @}
|
||||
Loading…
Reference in New Issue
Block a user