1/* 2 * Copyright 2014 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * John Scipione, jscipione@gmail.com 7 * 8 * Corresponds to: 9 * headers/os/interface/ScrollBar.h hrev47312 10 * src/kits/interface/ScrollBar.cpp hrev47312 11 */ 12 13 14/*! 15 \file ScrollBar.h 16 \ingroup interface 17 \ingroup libbe 18 \brief BScrollBar class definition. 19 \since BeOS R3 20*/ 21 22 23/*! 24 \class BScrollBar 25 \ingroup interface 26 \ingroup libbe 27 \brief User interface element used to scroll a target view vertically or 28 horizontally. 29 30 Scroll bars are usually added as siblings of the target view, that way 31 when the parent is resized the target view and scroll bars can be resized 32 as well. The BScrollView class conveniently provides such a container view 33 adding the scroll bars and target view making itself the parent. 34 35 Scroll bars control the target view, but a target can also be scrolled 36 independently by calling BView::ScrollTo() or BView::ScrollBy(). 37 When a target view is set to a BScrollBar, the view is notified and stores 38 a pointer to the BScrollBar object so that it can communicate its scroll 39 information back to the scroll bar. 40 41 \sa BView::ScrollTo() 42 \sa BView::ScrollBy() 43 \sa BView::ScrollBar() 44 45 \since BeOS R3 46*/ 47 48 49/*! 50 \fn BScrollBar::BScrollBar(BRect frame, const char* name, BView* target, 51 float min, float max, orientation direction) 52 \brief Instantiates a new scroll bar and connects it to the \a target 53 view. 54 55 The \a frame rectangle defines the location and size of the scroll bar 56 within its parent view. A horizontal scroll bar should be 57 \c B_H_SCROLL_BAR_HEIGHT pixels high, and a vertical scroll bar should be 58 \c B_V_SCROLL_BAR_WIDTH pixels wide. 59 60 Unlike most BView derived constructors in the Interface Kit this method 61 doesn't provide a resizing mode. Scroll bars are assigned a resizing 62 behavior based on their \a direction. Horizontal scroll bars resize 63 themselves horizontally (\c B_FOLLOW_LEFT_RIGHT | \c B_FOLLOW_BOTTOM) and 64 vertical scroll bars resize themselves vertically 65 (\c B_FOLLOW_TOP_BOTTOM | \c B_FOLLOW_RIGHT). 66 67 \param frame The \a frame rectangle of the scroll bar. 68 \param name The name of the scroll bar, can be \c NULL. 69 \param target The \a target view to scroll, can be \c NULL. 70 \param min The \a min scroll value. 71 \param max The \a max scroll value. 72 \param direction The scroll \a direction. Either \c B_HORIZONTAL 73 or \c B_VERTICAL. 74 75 \sa SetTarget() to set the \a target. 76 \sa SetRange() to set the \a min and \a max values. 77 \sa SetOrientation() to set the scroll bar \a direction. 78 79 \since BeOS R3 80*/ 81 82 83/*! 84 \fn BScrollBar::BScrollBar(const char* name, BView* target, 85 float min, float max, orientation direction) 86 \brief Instantiates a new scroll bar to be used as part of a layout and 87 connects it to the \a target view. 88 89 \param name The name of the scroll bar, can be \c NULL. 90 \param target The \a target view to scroll, can be \c NULL. 91 \param min The \a min scroll value. 92 \param max The \a max scroll value. 93 \param direction The scroll \a direction. Either \c B_HORIZONTAL 94 or \c B_VERTICAL. 95 96 \sa SetTarget() to set the \a target. 97 \sa SetRange() to set the \a min and \a max values. 98 \sa SetOrientation() to set the scroll bar \a direction. 99 100 \since Haiku R1 101*/ 102 103 104/*! 105 \fn BScrollBar::BScrollBar(BMessage* data) 106 \brief Archive constructor. 107 108 \param data The message \a data to construct the scroll bar from. 109 110 \since BeOS R3 111*/ 112 113 114/*! 115 \fn BScrollBar::~BScrollBar() 116 \brief Destructor method. 117 118 Deletes the scroll bar, sets the target to \c NULL and frees any 119 memory used. 120 121 \since BeOS R3 122*/ 123 124 125/*! 126 \name Archiving 127*/ 128 129 130//! @{ 131 132 133/*! 134 \fn BArchivable* BScrollBar::Instantiate(BMessage* data) 135 \brief Creates a new BScrollBar object from the \a data message. 136 137 \return A newly created scroll bar or \c NULL if the message doesn't 138 contain an archived BScrollBar object. 139 140 \since BeOS R3 141*/ 142 143 144/*! 145 \fn status_t BScrollBar::Archive(BMessage* data, bool deep) const 146 \brief Archives the object into the \a data message. 147 148 \param data A pointer to the BMessage object to archive the object into. 149 \param deep Whether or not to archive child views as well. 150 151 \return A status code, \c B_OK if everything went well or an error code 152 otherwise. 153 154 \since BeOS R3 155*/ 156 157 158//! @} 159 160 161/*! 162 \fn void BScrollBar::SetValue(float value) 163 \brief Sets the value of the scroll bar scrolling the scroll thumb and 164 target view accordingly. 165 166 Setting the \a value programmatically using this method causes the 167 ValueChanged() method to be called. 168 169 Derived classes can override this method to do something different than 170 scrolling the target view. 171 172 \param value The value to set the scroll bar value to, rounded to the 173 nearest integer. 174 175 \sa ValueChanged() 176 177 \since BeOS R3 178*/ 179 180 181/*! 182 \fn float BScrollBar::Value() const 183 \brief Returns the scroll bar's value. 184 185 \return The scroll bar's value as a float. 186 187 \since BeOS R3 188*/ 189 190 191/*! 192 \fn void BScrollBar::SetProportion(float value) 193 \brief Set the ratio of the size of a scroll knob to the scroll bar. 194 195 \note If \a value is outside the range 0.0 to 1.0 it is clipped 196 to that range. 197 198 \param value a number between 0.0 and 1.0 that represents the proportion of 199 the document that can be displayed within the target view. 200 201 \since BeOS R3 202*/ 203 204 205/*! 206 \fn float BScrollBar::Proportion() const 207 \brief Returns the ratio of the size of a scroll knob to the scroll bar. 208 209 \return A value between 0.0 and 1.0 as a float. 210 211 \since BeOS R3 212*/ 213 214 215/*! 216 \fn void BScrollBar::SetRange(float min, float max) 217 \brief Set the range of values that the scroll bar represents from \a min to 218 \a max. 219 220 These values should be calculated from the enclosing bounds of the target view. 221 If \a min and \a max are both 0 the scroll bar is disabled and the knob is not 222 drawn. 223 224 If the range changes such that the value is clipped SetValue() is called which 225 triggers ValueChanged() to be triggered. 226 227 \param min The \a min value of the range, rounded to the nearest integer. 228 \param max The \a max value of the range, rounded to the nearest integer. 229 230 \since BeOS R3 231*/ 232 233 234/*! 235 \fn void BScrollBar::GetRange(float* min, float* max) const 236 \brief Fills out \a min and \a max with the minimum and maximum range values. 237 238 \remark Either \a min or \a max may be set to \c NULL if you only want to get 239 the other one. 240 241 \param min A pointer to a float to be filled out with the \a min value. 242 \param max A pointer to a float to be filled out with the \a max value. 243 244 \since BeOS R3 245*/ 246 247 248/*! 249 \fn void BScrollBar::SetSteps(float smallStep, float largeStep) 250 \brief Sets how far the scroll bar moves when it is scrolled. 251 252 \note In BeOS R5, steps can be set only after the scroll bar is attached 253 to a window, probably because the data is kept server-side, in Haiku 254 this limitation has been removed. 255 256 \note The BeBook also says that we need to specify an integral value even 257 though the step values are floats, in Haiku we round the values 258 instead. 259 260 \param smallStep The value to move the scroll bar under normal conditions. 261 \param largeStep The value to move the scroll bar taking a large step, 262 this is usually triggered by holding down the \key{Shift} key while 263 scrolling. 264 265 \since BeOS R3 266*/ 267 268 269/*! 270 \fn void BScrollBar::GetSteps(float* smallStep, float* largeStep) const 271 \brief Fills out \a smallStop and \a largeStep with the small and large 272 step values respectively. 273 274 \remark Either \a smallStep or \a largeStep may be set to \c NULL if you 275 only want to get the other one. 276 277 \param smallStep A pointer to a float to be filled out with the small step 278 value. 279 \param largeStep A pointer to a float to be filled out with the large step 280 value. 281 282 \since BeOS R3 283*/ 284 285 286/*! 287 \fn void BScrollBar::SetTarget(BView* target) 288 \brief Sets the \a target view that the scroll bar operates on unsetting 289 the previous target. 290 291 \param target The \a target view to set. 292 293 \since BeOS R3 294*/ 295 296 297/*! 298 \fn void BScrollBar::SetTarget(const char* targetName) 299 \brief Sets the target view to the view identified by \a targetName 300 unsetting the previous target. 301 302 \note The BeOS R5 implementation crashes for \a targetName == \c NULL 303 and also does not modify the target if it can't be found. 304 305 \param targetName The name of the view to target. 306 307 \since BeOS R3 308*/ 309 310 311/*! 312 \fn BView* BScrollBar::Target() const 313 \brief Returns a pointer to the target view. 314 315 \return A pointer to a BView object that represents the target view or 316 \c NULL if the target is not set. 317 318 \since BeOS R3 319*/ 320 321 322/*! 323 \fn void BScrollBar::SetOrientation(orientation direction) 324 \brief Sets the \a direction of the scroll view. 325 326 \param direction Either \a B_HORIZONTAL or \a B_VERTICAL. 327 328 \since Haiku R1 329*/ 330 331 332/*! 333 \fn orientation BScrollBar::Orientation() const 334 \brief Returns the direction of the scroll bar. 335 336 \return Either \a B_HORIZONTAL or \a B_VERTICAL. 337 338 \since Haiku R1 339*/ 340 341 342/*! 343 \fn status_t BScrollBar::SetBorderHighlighted(bool highlight) 344 \brief Highlights or unhighlights the border of the scroll bar. 345 346 \param highlight \c true to turn highlighting on, \c false to remove it. 347 348 \return If successful returns \c B_OK, otherwise, returns \c B_ERROR. 349 350 \since Haiku R1 351*/ 352 353 354/*! 355 \name Hook Methods 356*/ 357 358 359//! @{ 360 361 362/*! 363 \fn void BScrollBar::AllAttached() 364 \copydoc BView::AllAttached() 365*/ 366 367 368/*! 369 \fn void BScrollBar::AllDetached() 370 \copydoc BView::AllDetached() 371*/ 372 373 374/*! 375 \fn void BScrollBar::AttachedToWindow() 376 \brief Hook method called when the scroll bar is attached to a window. 377 378 This method does nothing, unlike in BeOS R5. In BeOS scroll bars were 379 implemented directly in the App Server, the client BScrollBar was just a 380 proxy which needed to be synced up on AttachedToWindow(). On Haiku, scroll 381 bars are implemented more sanely and thus don't need to do this. 382 383 \copydetails BView::AttachedToWindow() 384*/ 385 386 387/*! 388 \fn void BScrollBar::DetachedFromWindow() 389 \copydoc BView::DetachedFromWindow() 390*/ 391 392 393/*! 394 \fn void BScrollBar::Draw(BRect updateRect) 395 \brief Draws the area of the scroll bar that intersects \a updateRect. 396 397 \param updateRect The rectangular area to be drawn. 398 399 \since BeOS R3 400*/ 401 402 403/*! 404 \fn void BScrollBar::FrameMoved(BPoint newPosition) 405 \brief Hook method called when the scroll bar is moved. 406 407 \copydetails BView::FrameMoved() 408*/ 409 410 411/*! 412 \fn void BScrollBar::FrameResized(float newWidth, float newHeight) 413 \brief Hook method called when the scroll bar is resized. 414 415 \copydetails BView::FrameResized() 416*/ 417 418 419/*! 420 \fn void BScrollBar::MessageReceived(BMessage* message) 421 \brief Handle \a message received by the associated looper. 422 423 Calls ValueChanged() in response to \c B_VALUE_CHANGED. 424 Scrolls the view in response to \c B_MOUSE_WHEEL_CHANGED. 425 426 \copydetails BView::MessageReceived() 427*/ 428 429 430/*! 431 \fn void BScrollBar::MouseDown(BPoint where) 432 \brief Hook method called when a mouse button is pressed. 433 434 Begins scrolling the target view in response to a mouse click. If the 435 user clicked the scroll bar thumb this begins scrolling and continues 436 in MouseMoved() ending on MouseUp(). If the user clicked on one of the 437 scroll arrows the view is scrolled a small amount, if the user clicks 438 on an area of the scroll view outside the arrows and thumb the view is 439 scrolled by a larger amount. 440 441 \copydetails BView::MouseDown() 442*/ 443 444 445/*! 446 \fn void BScrollBar::MouseMoved(BPoint where, uint32 code, 447 const BMessage* dragMessage) 448 \brief Hook method called when the mouse is moved. 449 450 If the user clicked on the scroll bar thumb the view is scrolled as the user 451 moves the mouse up and down or left and right. 452 453 \copydetails BView::MouseMoved() 454*/ 455 456 457/*! 458 \fn void BScrollBar::MouseUp(BPoint where) 459 \brief Hook method called when a mouse button is released. 460 461 Finishes scrolling and redraws the scroll bar if necessary. 462 463 \copydetails BView::MouseUp() 464*/ 465 466 467/*! 468 \fn void BScrollBar::ValueChanged(float newValue) 469 \brief Hook method called when the value of the scroll bar changes. 470 471 \param newValue The new scroll bar value. 472 473 \since BeOS R3 474*/ 475 476 477/*! 478 \fn void BScrollBar::WindowActivated(bool active) 479 \copydoc BView::WindowActivated() 480*/ 481 482 483//! @} 484 485 486/*! 487 \fn void BScrollBar::ResizeToPreferred() 488 \copydoc BView::ResizeToPreferred() 489*/ 490 491 492/*! 493 \fn void BScrollBar::GetPreferredSize(float* _width, float* _height) 494 \brief Fill out the preferred width and height of the scroll bar 495 into the \a _width and \a _height parameters. 496 497 \copydetails BView::GetPreferredSize() 498*/ 499 500 501/*! 502 \fn void BScrollBar::MakeFocus(bool focus) 503 \brief Makes the scroll bar the current focus view of the window or gives up 504 being the window's focus view. 505 506 \copydetails BView::MakeFocus() 507*/ 508 509 510/*! 511 \fn BSize BScrollBar::MinSize() 512 \brief Return the scroll bar's minimum size. 513 514 \return The minimum size of the scroll bar as a BSize. 515 516 \sa BAbstractLayout::MinSize() 517 518 \since Haiku R1 519*/ 520 521 522/*! 523 \fn BSize BScrollBar::MaxSize() 524 \brief Return the scroll bar's maximum size. 525 526 \return The maximum size of the scroll bar as a BSize. 527 528 \sa BAbstractLayout::MaxSize() 529 530 \since Haiku R1 531*/ 532 533 534/*! 535 \fn BSize BScrollBar::PreferredSize() 536 \brief Return the scroll bar's preferred size. 537 538 \return The preferred size of the scroll bar as a BSize. 539 540 \sa BAbstractLayout::PreferredSize() 541 542 \since Haiku R1 543*/ 544 545 546/*! 547 \fn status_t BScrollBar::Perform(perform_code code, void* _data) 548 \brief Perform some action. (Internal Method) 549 550 \since Haiku R1 551*/ 552 553 554/*! 555 \name Scripting 556*/ 557 558 559//! @{ 560 561 562/*! 563 \fn status_t BScrollBar::GetSupportedSuites(BMessage* message) 564 \brief Reports the suites of messages and specifiers understood by the 565 scroll bar. 566 567 \copydetails BView::GetSupportedSuites() 568*/ 569 570 571/*! 572 \fn BHandler* BScrollBar::ResolveSpecifier(BMessage* message, int32 index, 573 BMessage* specifier, int32 what, const char* property) 574 \brief Determine the proper handler for a scripting message. 575 576 \copydetails BView::ResolveSpecifier() 577*/ 578 579 580//! @} 581