1/* 2 * Copyright 2020 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Niels Sascha Reedijk, niels.reedijk@gmail.com 7 * 8 * Reviewers: 9 * Adrien Destugues, pulkomandy@pulkomandy.tk 10 * 11 * Corresponds to: 12 * headers/os/interface/SplitView.h hrev49977 13 * src/kits/interface/SplitView.cpp hrev43279 14 */ 15 16 17/*! 18 \file SplitView.h 19 \ingroup layout 20 \ingroup libbe 21 \brief Provides the BSplitView class. 22 23 \since Haiku R1 24*/ 25 26 27/*! 28 \class BSplitView 29 \ingroup layout 30 \ingroup libbe 31 \brief A container with two or more sections, with dividers in between, 32 so that a user can manipulate the size of the sections by dragging 33 a slider. 34 35 This container view consists one of more items, that are laid out 36 horizontally or vertically. Between two adjoining items, there is a 37 splitter. This splitter allows the user to change how the space between the 38 individual items is divided. 39 40 The screenshot below shows the BSplitView being used in HaikuDepot. The 41 BSplitView is the main container of the window, in this case with a 42 \ref B_VERTICAL layout. The top part contains the list of packages, and 43 some filter tools. At the bottom are individual package details. In between 44 the two visual elements there is a dotted line, indicating the draggable 45 separator. At the right hand of this separator, above the \b Install 46 button, you can see that the mouse cursor changed into the double arrow, 47 indicating the user that the element is dragable. 48 49 \image html BSplitView_HaikuDepot.png 50 51 Because of the dynamic nature of the size of the sections within the 52 split view, it is best to use this container with the \link layout layout 53 system\endlink. It is fully supported by the layout builder utilities. See 54 the \ref BLayoutBuilder::Split<> documentation for the builder that 55 accompanies this view. 56 57 The container has the following properties: 58 - \b Insets are the padding for the split view. 59 - \b Spacing is the spacing between the components. 60 - \b Orientation is whether the splits are horizontal or vertical. 61 - \b Splitter \b size is the size of the splitter. 62 63 Specifically for individual elements, the following properties may also 64 be set: 65 - \b Weight for the weight of the item within the split view (determines 66 how space is allocated between the items). 67 - \b Collapsible determines if an element is collapsible, meaning the user 68 can drag the splitter as such as to hide the item completely. If an item 69 is not collapsible, at least a part of the item will always be visible 70 to the user. 71 72 \related The \ref BGroupView essentially has the same properties for 73 organizing the layout items, though it does not offer the functionality 74 for users to change the size of the elements. 75 76 \since Haiku R1 77*/ 78 79 80/*! 81 \fn BSplitView::BSplitView(orientation orientation=B_HORIZONTAL, float spacing=B_USE_DEFAULT_SPACING) 82 \brief Creates a new split view. 83 84 \param orientation The orientation of the splits. 85 \param spacing The spacing in between the elements. 86 87 \since Haiku R1 88*/ 89 90 91/*! 92 \fn BSplitView::BSplitView(BMessage *from) 93 \brief Unarchive a split view. 94 95 This method is usually not called directly, if you want to build a 96 split view from an archived message you should call Instantiate() instead 97 because it can handle errors properly. 98 99 \param from The \ref BMessage that contains the split view. 100 101 \since Haiku R1 102*/ 103 104 105/*! 106 \fn virtual BSplitView::~BSplitView() 107 \brief Destructor. 108 109 \since Haiku R1 110*/ 111 112 113/*! 114 \fn void BSplitView::SetInsets(float left, float top, float right, float bottom) 115 \brief Set the insets between the bounds of the view and the inner 116 elements. 117 118 \param left The left inset. 119 \param top The top inset. 120 \param right The right inset. 121 \param bottom The bottom inset. 122 123 \since Haiku R1 124*/ 125 126 127/*! 128 \fn void BSplitView::SetInsets(float horizontal, float vertical) 129 \brief Set the insets between the bounds of the view and the inner 130 elements. 131 132 \param horizontal The left and right inset. 133 \param vertical The top and bottom inset. 134 135 \since Haiku R1 136*/ 137 138 139/*! 140 \fn void BSplitView::SetInsets(float insets) 141 \brief Set the insets between the bounds of the view and the inner 142 elements. 143 144 \param insets The value for the left, top, right and bottom inset. 145 146 \since Haiku R1 147*/ 148 149 150/*! 151 \fn void BSplitView::GetInsets(float *left, float *top, float *right, float *bottom) const 152 \brief Get the insets that apply to this view. 153 154 You may pass \c NULL for any of the parameters, if you do not wish to 155 retrieve their value. 156 157 \param[out] left Will be set to the left inset. 158 \param[out] top Will be set to the top inset. 159 \param[out] right Will be set to the right inset. 160 \param[out] bottom Will be set to the bottom inset. 161 162 \since Haiku R1 163*/ 164 165 166/*! 167 \fn float BSplitView::Spacing() const 168 \brief Get the spacing between elements in this view. 169 170 \return The spacing between elements as a \c float. 171 172 \since Haiku R1 173*/ 174 175 176/*! 177 \fn void BSplitView::SetSpacing(float spacing) 178 \brief Set the spacing between elements in this view. 179 180 \param spacing The desired spacing between elements. This will apply to all 181 elements. 182 183 \since Haiku R1 184*/ 185 186 187/*! 188 \fn orientation BSplitView::Orientation() const 189 \brief Get the orientation of the elements in this view. 190 191 \retval B_HORIZONTAL The elements are ordered left-to-right. 192 \retval B_VERTICAL The elements are ordered top-to-bottom. 193 194 \since Haiku R1 195*/ 196 197 198/*! 199 \fn void BSplitView::SetOrientation(orientation orientation) 200 \brief Set the orientation of the elements in this view. 201 202 \param orientation May be \ref B_HORIZONTAL or \ref B_VERTICAL. 203 204 \since Haiku R1 205*/ 206 207 208/*! 209 \fn float BSplitView::SplitterSize() const 210 \brief Get the size of the splitter(s) in this view. 211 212 \return The size of the splitter(s). 213 214 \since Haiku R1 215*/ 216 217 218/*! 219 \fn void BSplitView::SetSplitterSize(float size) 220 \brief Set the size of the splitter(s) in this view. 221 222 \param size The size as a \c float that will be applied to all splitters 223 in this view. 224 225 \since Haiku R1 226*/ 227 228 229/*! 230 \fn int32 BSplitView::CountItems() const 231 \brief The number of items in this view. 232 233 \return Returns the number of items in this view. The splitters themselves 234 are not included in this number. 235 236 \since Haiku R1 237*/ 238 239 240/*! 241 \fn float BSplitView::ItemWeight(int32 index) const 242 \brief Get the item weight for the item at the \a index. 243 244 \param index The index of the item (zero-based). 245 246 \return The weight of the item, or \c 0.0 if there is no item at \a index. 247 248 \since Haiku R1 249*/ 250 251 252/*! 253 \fn float BSplitView::ItemWeight(BLayoutItem *item) const 254 \brief Get the item weight for an existing \a item. 255 256 \param item An existing layout item object. 257 258 \return The weight of the \a item, or \c 0.0 if the item is not associated 259 with this view. 260 261 \since Haiku R1 262*/ 263 264 265/*! 266 \fn void BSplitView::SetItemWeight(int32 index, float weight, bool invalidateLayout) 267 \brief Set the weight of the item at \a index. 268 269 The weight is relative to all other items in the layout, and determines how 270 the available space is distributed over the items in the layout. 271 272 \param index The index of the item (zero-based). 273 \param weight The weight of the item. 274 \param invalidateLayout When \c true, calls 275 \ref BLayout::InvalidateLayout() to recalculate the layout. 276 277 \since Haiku R1 278*/ 279 280 281/*! 282 \fn void BSplitView::SetItemWeight(BLayoutItem *item, float weight) 283 \brief Set the weight of the \a item. 284 285 The weight is relative to all other items in the layout, and determines how 286 the available space is distributed over the items in the layout. 287 288 \param item The item within this view that the weight applies to. 289 \param weight The weight of the item. 290 291 \since Haiku R1 292*/ 293 294 295/*! 296 \fn bool BSplitView::IsCollapsible(int32 index) const 297 \brief Get whether the item at \a index is collapsible. 298 299 \param index The index of the item (zero-based). 300 301 \retval true The user can collapse the item. 302 \retval false The user cannot collapse the item. 303 304 \since Haiku R1 305*/ 306 307 308/*! 309 \fn void BSplitView::SetCollapsible(bool collapsible) 310 \brief Set the whether all the layout items in this view are collapsible. 311 312 \param collapsible \c true if all items in this layout are collapsible, 313 \c false if they are not. 314 315 \since Haiku R1 316*/ 317 318 319/*! 320 \fn void BSplitView::SetCollapsible(int32 index, bool collapsible) 321 \brief Set whether the item at \a index is collapsible. 322 323 \param index The index of the item (zero-based). 324 \param collapsible \c true if the user may collaps the item, \c false if 325 they may not. 326 327 \since Haiku R1 328*/ 329 330 331/*! 332 \fn void BSplitView::SetCollapsible(int32 first, int32 last, bool collapsible) 333 \brief Set whether the items from \a first to \a last are collapsible. 334 335 \param first The index of the first item that you want the setting to apply 336 to (zero-based). 337 \param last The index of the last item that you want the setting to apply 338 to (zero-based). 339 \param collapsible \c true if the user may collaps the item, \c false if 340 they may not. 341 342 \since Haiku R1 343*/ 344 345 346/*! 347 \fn bool BSplitView::IsItemCollapsed(int32 index) const 348 \brief Check whether the item at \a index is collapsed. 349 350 \param index The index of the item (zero-based). 351 352 \retval true The item is collapsed. 353 \retval false The item is not collapsed. 354 355 \since Haiku R1 356*/ 357 358 359/*! 360 \fn void BSplitView::SetItemCollapsed(int32 index, bool collapsed) 361 \brief Set whether the item at \a index is displayed as collapsed. 362 363 \param index The index of the item (zero-based). 364 \param collapsed \c true if the item should be rendered collapsed, \c 365 false if it needs to be visible. 366 367 \since Haiku R1 368*/ 369 370 371/*! 372 \fn void BSplitView::AddChild(BView *child, BView *sibling=NULL) 373 \brief Add a \a child to the view. 374 375 Passthrough for \ref BView::AddChild(BView *child, BView *sibling). This 376 bypasses the layout system, so only use it when you know what you are 377 doing. 378 379 \since Haiku R1 380*/ 381 382 383/*! 384 \fn bool BSplitView::AddChild(BView *child, float weight) 385 \brief Add a \a child with a \a weight. 386 387 The view will be added at the end of the existing layout items, meaning it 388 will be placed to the right or bottom of existing items. 389 390 \param child The view that should be added as a child. The ownership is 391 transferred to this view. 392 \param weight The weight of the item. 393 394 \return \c true when succesfully, \c false if there was an error. 395 396 \since Haiku R1 397*/ 398 399 400/*! 401 \fn bool BSplitView::AddChild(int32 index, BView *child, float weight) 402 \brief Add a \a child at \a index with a \a weight. 403 404 \param index The desired position for the \a child. Existing items will be 405 shifted to the right or down based on the orientation. If the index is 406 higher than the number of items, the item will be added after farmost 407 item. The index is zero-based. 408 \param child The view that should be added as a child. The ownership is 409 transferred to this view. 410 \param weight The weight of the item. 411 412 \return \c true when succesfully, \c false if there was an error. 413 414 \since Haiku R1 415*/ 416 417 418/*! 419 \fn bool BSplitView::AddChild(BLayoutItem *child) 420 \brief Add a \a child. 421 422 The child will be added at the end of the existing layout items, meaning it 423 will be placed to the right or bottom of existing items. 424 425 \param child The layout item to add. 426 427 \return \c true when succesfully, \c false if there was an error. 428 429 \since Haiku R1 430*/ 431 432 433/*! 434 \fn bool BSplitView::AddChild(BLayoutItem *child, float weight) 435 \brief Add a \a child with a \a weight. 436 437 The child will be added at the end of the existing layout items, meaning it 438 will be placed to the right or bottom of existing items. 439 440 \param child The layout item to add. 441 \param weight The weight of the item. 442 443 \return \c true when succesfully, \c false if there was an error. 444 445 \since Haiku R1 446*/ 447 448 449/*! 450 \fn bool BSplitView::AddChild(int32 index, BLayoutItem *child, float weight) 451 \brief Add a \a child at \a index with a \a weight. 452 453 \param index The desired position for the \a child. Existing items will be 454 shifted to the right or down based on the orientation. If the index is 455 higher than the number of items, the item will be added after farmost 456 item. The index is zero-based. 457 \param child The layout item to add. 458 \param weight The weight of the item. 459 460 \return \c true when succesfully, \c false if there was an error. 461 462 \since Haiku R1 463*/ 464 465 466/*! 467 \fn virtual void BSplitView::AttachedToWindow() 468 \brief Hook method overridden from BView. 469 470 \since Haiku R1 471*/ 472 473 474/*! 475 \fn virtual void BSplitView::Draw(BRect updateRect) 476 \brief Hook method overridden from BView. 477 478 \since Haiku R1 479*/ 480 481 482/*! 483 \fn virtual void BSplitView::DrawAfterChildren(BRect updateRect) 484 \brief Hook method overridden from BView. 485 486 \since Haiku R1 487*/ 488 489 490/*! 491 \fn virtual void BSplitView::MouseDown(BPoint where) 492 \brief Hook method overridden from BView. 493 494 \since Haiku R1 495*/ 496 497 498/*! 499 \fn virtual void BSplitView::MouseUp(BPoint where) 500 \brief Hook method overridden from BView. 501 502 \since Haiku R1 503*/ 504 505 506/*! 507 \fn virtual void BSplitView::MouseMoved(BPoint where, uint32 transit, const BMessage *message) 508 \brief Hook method overridden from BView. 509 510 \since Haiku R1 511*/ 512 513 514/*! 515 \fn virtual void BSplitView::MessageReceived(BMessage *message) 516 \brief Hook method overridden from BView. 517 518 \since Haiku R1 519*/ 520 521 522/*! 523 \fn virtual void BSplitView::SetLayout(BLayout *layout) 524 \brief Hook method overridden from BView. 525 526 \since Haiku R1 527*/ 528 529 530/*! 531 \fn virtual status_t BSplitView::Archive(BMessage *into, bool deep=true) const 532 \copydoc BArchivable::Archive() 533*/ 534 535 536/*! 537 \fn virtual status_t BSplitView::Perform(perform_code d, void *arg) 538 \brief Hook method overridden from BView. 539 540 \since Haiku R1 541*/ 542 543 544/*! 545 \fn static BArchivable* BSplitView::Instantiate(BMessage *from) 546 \brief Instantiate the view from the message \a from. 547 548 \since Haiku R1 549*/ 550 551 552/*! 553 \fn virtual status_t BSplitView::AllArchived(BMessage *into) const 554 \brief Hook method overridden from BArchivable. 555 556 \since Haiku R1 557*/ 558 559 560/*! 561 \fn virtual status_t BSplitView::AllUnarchived(const BMessage *from) 562 \brief Hook method overridden from BArchivable. 563 564 \since Haiku R1 565*/ 566 567 568/*! 569 \fn virtual void BSplitView::DrawSplitter(BRect frame, const BRect &updateRect, orientation orientation, bool pressed) 570 \brief Hook method called when the splitter needs to be drawn. 571 572 This method is called in the context of a \ref BView::Draw() operation. 573 Derived classes can override this to draw a splitter. 574 575 \since Haiku R1 576*/ 577
