1/* 2 * Copyright 2003-2014 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Marc Flerackers, mflerackers@androme.be 7 * John Scipione, jscipione@gmail.com 8 * 9 * Corresponds to: 10 * headers/os/interface/Shape.h hrev47496 11 * src/kits/interface/Shape.cpp hrev47496 12 */ 13 14 15/*! 16 \file Shape.h 17 \ingroup interface 18 \ingroup libbe 19 \brief BShape and BShapeIterator class definitions. 20*/ 21 22 23/*! 24 \class BShapeIterator 25 \ingroup interface 26 \ingroup libbe 27 \brief Allows you to iterate through BShape operations. 28 29 You should override this class and implement the IterateMoveTo(), 30 IterateLineTo(), IterateBezierTo(), IterateClose(), and IterateArcTo() 31 methods which correspond to BShape::MoveTo(), BShape::LineTo(), 32 BShape::BezierTo(), BShape::Close() and BShape::ArcTo() respectively. 33 34 \sa BShape 35 36 \since BeOS R4 37*/ 38 39 40/*! 41 \fn BShapeIterator::BShapeIterator() 42 \brief Constructor, does nothing. 43 44 This method does nothing and should be implemented by derived classes. 45 46 \since BeOS R4 47*/ 48 49 50/*! 51 \fn BShapeIterator::~BShapeIterator() 52 \brief Destructor, does nothing. 53 54 This method does nothing and should be implemented by derived classes. 55 56 \since BeOS R4 57*/ 58 59 60/*! 61 \fn status_t BShapeIterator::Iterate(BShape* shape) 62 \brief Iterates over each operation that make up the BShape calling 63 IterateMoveTo(), IterateLineTo(), IterateBezierTo(), 64 IterateClose() or IterateArcTo() depending on the operation. 65 66 \brief shape The BShape object to iterate through. 67 68 \return Always returns \c B_OK. You should override this method 69 to return an appropriate status code. 70 71 \since BeOS R4 72*/ 73 74 75/*! 76 \fn status_t BShapeIterator::IterateMoveTo(BPoint* point) 77 \brief Called by Iterate() to act on \a point. 78 79 This method does nothing and should be implemented by derived classes. 80 81 \param point The point to act on. 82 83 \return Always returns \c B_OK. You should override this method 84 to return an appropriate status code. 85 86 \since BeOS R4 87*/ 88 89 90/*! 91 \fn status_t BShapeIterator::IterateLineTo(int32 lineCount, 92 BPoint* linePoints) 93 \brief Called by Iterate() to act on \a lineCount lines comprised of the 94 points specified by \a linePoints. 95 96 This method does nothing and should be implemented by derived classes. 97 98 \param lineCount The number of points in \a linePoints. 99 \param linePoints The list of points of lines to act on. 100 101 \return Always returns \c B_OK. You should override this method 102 to return an appropriate status code. 103 104 \since BeOS R4 105*/ 106 107 108/*! 109 \fn status_t BShapeIterator::IterateBezierTo(int32 bezierCount, 110 BPoint* bezierPoints) 111 \brief Called by Iterate() to act on \a bezierCount Bézier curves 112 comprised of the points specified by \a bezierPoints. 113 114 This method does nothing and should be implemented by derived classes. 115 116 \param bezierCount The number of points in \a bezierPoints. 117 \param bezierPoints The list of Bézier curve points to act on. 118 119 \return Always returns \c B_OK. You should override this method 120 to return an appropriate status code. 121 122 \since BeOS R4 123*/ 124 125 126/*! 127 \fn status_t BShapeIterator::IterateClose() 128 \brief Called by Iterate() to close the BShape. 129 130 This method does nothing and should be implemented by derived classes. 131 132 \return Always returns \c B_OK. You should override this method 133 to return an appropriate status code. 134 135 \since BeOS R4 136*/ 137 138 139/*! 140 \fn status_t BShapeIterator::IterateArcTo(float& rx, float& ry, 141 float& angle, bool largeArc, bool counterClockWise, BPoint& point) 142 \brief Called by Iterate() to act on an arc. 143 144 \param rx The horizontal radius of the arc to act on. 145 \param ry The vertical radius of the arc to act on. 146 \param angle The starting angle of the arc in degrees to act on. 147 \param largeArc Whether or not to draw a large arc. 148 \param counterClockWise \c true if the arc is drawn counter-clockwise, \c false 149 if the arc is drawn clockwise. 150 \param point The center point of the arc to act on. 151 152 This method does nothing and should be implemented by derived classes. 153 154 \return Always returns \c B_OK. You should override this method 155 to return an appropriate status code. 156 157 \since Haiku R1 158*/ 159 160 161/*! 162 \class BShape 163 \ingroup interface 164 \ingroup libbe 165 \brief Encapsulates a Postscript-style "path". 166 167 You can obtain the outlines of characters from a string as BShape objects 168 by calling BFont::GetGlyphShapes(). 169 170 \since BeOS R4 171*/ 172 173 174/*! 175 \fn BShape::BShape() 176 \brief Creates an empty BShape object. 177 178 \since BeOS R4 179*/ 180 181 182/*! 183 \fn BShape::BShape(const BShape& other) 184 \brief Creates a new BShape object as a copy of \a other. 185 186 \param other The BShape object to copy from. 187 188 \since BeOS R4 189*/ 190 191 192/*! 193 \fn BShape::BShape(BMessage* archive) 194 \brief Creates a new BShape message from an \a archive message. 195 196 You should call Instantiate() instead as it will validate whether 197 or not the object was created successfully. 198 199 \param archive The BMessage object to construct the data from. 200 201 \since BeOS R4 202*/ 203 204 205/*! 206 \fn BShape::~BShape() 207 \brief Destructor, deletes all associated data. 208 209 \since BeOS R4 210*/ 211 212 213/*! 214 \name Archiving 215*/ 216 217 218//! @{ 219 220 221/*! 222 \fn status_t BShape::Archive(BMessage* archive, bool deep) const 223 \brief Archives the BShape object to a BMessage. 224 225 \param archive The BMessage object to archive the BShape data to. 226 \param deep Currently unused. 227 228 \return A status code, \c B_OK on scucess or an error code otherwise. 229 230 \since BeOS R4 231*/ 232 233 234/*! 235 \fn BArchivable* BShape::Instantiate(BMessage* archive) 236 \brief Creates a new BShape object from an \a archive message. 237 238 \param archive The BMessage object to construct the BShape data from. 239 240 \return A new BShape object or \c NULL if \a archive was invalid. 241 242 \since BeOS R4 243*/ 244 245 246//! @} 247 248 249/*! 250 \name Operators 251*/ 252 253 254//! @{ 255 256 257/*! 258 \fn BShape& BShape::operator=(const BShape& other) 259 \brief Constructs a BShape object as a copy of \a other by overloading 260 the = operator. 261 262 \param other The BShape object to copy from. 263 264 \brief Always returns *this. 265 266 \since Haiku R1 267*/ 268 269 270/*! 271 \fn bool BShape::operator==(const BShape& other) const 272 \brief Returns whether or not the contents of this BShape and \a other 273 contain the same data. 274 275 \return \c true if the contents are equal, \c false otherwise. 276 277 \since Haiku R1 278*/ 279 280 281/*! 282 \fn bool BShape::operator!=(const BShape& other) const 283 \brief Returns whether or not the contents of this BShape and \a other 284 do NOT contain the same data. 285 286 \return \c true if the contents are NOT equal, \c false otherwise. 287 288 \since Haiku R1 289*/ 290 291 292//! @} 293 294 295/*! 296 \fn void BShape::Clear() 297 \brief Deletes all data returning the BShape to an empty state. 298 299 \since BeOS R4 300*/ 301 302 303/*! 304 \fn BRect BShape::Bounds() const 305 \brief Returns a BRect that encloses all points in the BShape. 306 307 \warning This implementation doesn't take into account curves at all. 308 309 \since BeOS R4 310*/ 311 312 313/*! 314 \fn BPoint BShape::CurrentPosition() const 315 \brief Returns the current end point of the path. 316 317 \return The current end point of the path or \c B_ORIGIN if no points have 318 been added yet. 319 320 \since Haiku R1 321*/ 322 323 324/*! 325 \fn status_t BShape::AddShape(const BShape* otherShape) 326 \brief Adds the lines and curves of \a otherShape to BShape. 327 328 \return Always returns \c B_OK. 329 330 \since BeOS R4 331*/ 332 333 334/*! 335 \name Operations 336*/ 337 338 339//! @{ 340 341 342/*! 343 \fn status_t BShape::MoveTo(BPoint point) 344 \brief Adds a "move to" operation to the BShape. 345 346 The next LineTo() or BezierTo() will begin at \a point allowing you to 347 create noncontiguous shapes. 348 349 \param point The point to start the next LineTo() or BezierTo() at. 350 351 \return Returns a status code, \c B_OK on success or an error code 352 otherwise. 353 \retval B_OK The operation was added successfully. 354 \retval B_NO_MEMORY Ran out of memory while trying to add the operation. 355 356 \since BeOS R4 357*/ 358 359 360/*! 361 \fn status_t BShape::LineTo(BPoint point) 362 \brief Adds a "draw line" operation to the BShape. 363 364 A line will be drawn from the previous point to the \a point specified. 365 366 \param point The point to draw a line to starting at the previous location. 367 368 \return Returns a status code, \c B_OK on success or an error code 369 otherwise. 370 \retval B_OK The operation was added successfully. 371 \retval B_NO_MEMORY Ran out of memory while trying to add the operation. 372 373 \since BeOS R4 374*/ 375 376 377/*! 378 \fn status_t BShape::BezierTo(BPoint controlPoints[3]) 379 \brief Adds a "draw Bézier curve" operation to the BShape. 380 381 A Bézier curve is drawn that begins at the current point and is made up 382 of the specified \a controlPoints. 383 384 \param controlPoints The points that make up the Bézier curve. 385 386 \return Returns a status code, \c B_OK on success or an error code 387 otherwise. 388 \retval B_OK The operation was added successfully. 389 \retval B_NO_MEMORY Ran out of memory while trying to add the operation. 390 391 \since BeOS R4 392*/ 393 394 395/*! 396 \fn status_t BShape::BezierTo(const BPoint& control1, 397 const BPoint& control2, const BPoint& endPoint) 398 \brief Adds a "draw Bézier curve" operation to the BShape. 399 400 A Bézier curve is drawn that begins at the current point and is made up 401 of the specified points. 402 403 \param control1 The first control point of the Bézier curve. 404 \param control2 The second control point of the Bézier curve. 405 \param endPoint The end point of the Bézier curve. 406 407 \return Returns a status code, \c B_OK on success or an error code 408 otherwise. 409 \retval B_OK The operation was added successfully. 410 \retval B_NO_MEMORY Ran out of memory while trying to add the operation. 411 412 \since Haiku R1 413*/ 414 415 416/*! 417 \fn status_t BShape::ArcTo(float rx, float ry, float angle, bool largeArc, 418 bool counterClockWise, const BPoint& point) 419 \brief Adds a "draw arc" operation to the BShape. 420 421 An arc is draw that begins at the current point and is specified by the 422 parameters to this method. 423 424 \param rx The horizontal radius of the arc. 425 \param ry The vertical radius of the arc. 426 \param angle The starting angle of the arc in degrees. 427 \param largeArc Whether or not to draw a large arc. 428 \param counterClockWise \c true to draw the arc counter-clockwise, \c false 429 to draw the arc clockwise. 430 \param point The center point of the arc. 431 432 \return Returns a status code, \c B_OK on success or an error code 433 otherwise. 434 \retval B_OK The operation was added successfully. 435 \retval B_NO_MEMORY Ran out of memory while trying to add the operation. 436 437 \since Haiku R1 438*/ 439 440 441/*! 442 \fn status_t BShape::Close() 443 \brief Adds an operation to close the BShape once it is fully constructed. 444 445 \return Returns a status code, \c B_OK on success or an error code 446 otherwise. 447 \retval B_OK The operation was added successfully. 448 \retval B_NO_MEMORY Ran out of memory while trying to add the operation. 449 450 \return Returns a status code, \c B_OK on success or an error code 451 otherwise. 452 \retval B_OK The operation was added successfully. 453 \retval B_NO_MEMORY Ran out of memory while trying to add the operation. 454 455 \since BeOS R4 456*/ 457 458 459//! @} 460