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 \param from The \ref BMessage that contains the split view. 96 97 \since Haiku R1 98*/ 99 100 101/*! 102 \fn virtual virtual BSplitView::~BSplitView() 103 \brief Destructor. 104 105 \since Haiku R1 106*/ 107 108 109/*! 110 \fn void BSplitView::SetInsets(float left, float top, float right, float bottom) 111 \brief Set the insets between the bounds of the view and the inner 112 elements. 113 114 \param left The left inset. 115 \param top The top inset. 116 \param right The right inset. 117 \param bottom The bottom inset. 118 119 \since Haiku R1 120*/ 121 122 123/*! 124 \fn void BSplitView::SetInsets(float horizontal, float vertical) 125 \brief Set the insets between the bounds of the view and the inner 126 elements. 127 128 \param horizontal The left and right inset. 129 \param vertical The top and bottom inset. 130 131 \since Haiku R1 132*/ 133 134 135/*! 136 \fn void BSplitView::SetInsets(float insets) 137 \brief Set the insets between the bounds of the view and the inner 138 elements. 139 140 \param insets The value for the left, top, right and bottom inset. 141 142 \since Haiku R1 143*/ 144 145 146/*! 147 \fn void BSplitView::GetInsets(float *left, float *top, float *right, float *bottom) const 148 \brief Get the insets that apply to this view. 149 150 You may pass \c NULL for any of the parameters, if you do not wish to 151 retrieve their value. 152 153 \param[out] left Will be set to the left inset. 154 \param[out] top Will be set to the top inset. 155 \param[out] right Will be set to the right inset. 156 \param[out] bottom Will be set to the bottom inset. 157 158 \since Haiku R1 159*/ 160 161 162/*! 163 \fn float BSplitView::Spacing() const 164 \brief Get the spacing between elements in this view. 165 166 \return The spacing between elements as a \c float. 167 168 \since Haiku R1 169*/ 170 171 172/*! 173 \fn void BSplitView::SetSpacing(float spacing) 174 \brief Set the spacing between elements in this view. 175 176 \param spacing The desired spacing between elements. This will apply to all 177 elements. 178 179 \since Haiku R1 180*/ 181 182 183/*! 184 \fn orientation BSplitView::Orientation() const 185 \brief Get the orientation of the elements in this view. 186 187 \retval B_HORIZONTAL The elements are ordered left-to-right. 188 \retval B_VERTICAL The elements are ordered top-to-bottom. 189 190 \since Haiku R1 191*/ 192 193 194/*! 195 \fn void BSplitView::SetOrientation(orientation orientation) 196 \brief Set the orientation of the elements in this view. 197 198 \param orientation May be \ref B_HORIZONTAL or \ref B_VERTICAL. 199 200 \since Haiku R1 201*/ 202 203 204/*! 205 \fn float BSplitView::SplitterSize() const 206 \brief Get the size of the splitter(s) in this view. 207 208 \return The size of the splitter(s). 209 210 \since Haiku R1 211*/ 212 213 214/*! 215 \fn void BSplitView::SetSplitterSize(float size) 216 \brief Set the size of the splitter(s) in this view. 217 218 \param size The size as a \c float that will be applied to all splitters 219 in this view. 220 221 \since Haiku R1 222*/ 223 224 225/*! 226 \fn int32 BSplitView::CountItems() const 227 \brief The number of items in this view. 228 229 \return Returns the number of items in this view. The splitters themselves 230 are not included in this number. 231 232 \since Haiku R1 233*/ 234 235 236/*! 237 \fn float BSplitView::ItemWeight(int32 index) const 238 \brief Get the item weight for the item at the \a index. 239 240 \param index The index of the item (zero-based). 241 242 \return The weight of the item, or \c 0.0 if there is no item at \a index. 243 244 \since Haiku R1 245*/ 246 247 248/*! 249 \fn float BSplitView::ItemWeight(BLayoutItem *item) const 250 \brief Get the item weight for an existing \a item. 251 252 \param item An existing layout item object. 253 254 \return The weight of the \a item, or \c 0.0 if the item is not associated 255 with this view. 256 257 \since Haiku R1 258*/ 259 260 261/*! 262 \fn void BSplitView::SetItemWeight(int32 index, float weight, bool invalidateLayout) 263 \brief Set the weight of the item at \a index. 264 265 The weight is relative to all other items in the layout, and determines how 266 the available space is distributed over the items in the layout. 267 268 \param index The index of the item (zero-based). 269 \param weight The weight of the item. 270 \param invalidateLayout When \c true, calls 271 \ref BLayout::InvalidateLayout() to recalculate the layout. 272 273 \since Haiku R1 274*/ 275 276 277/*! 278 \fn void BSplitView::SetItemWeight(BLayoutItem *item, float weight) 279 \brief Set the weight of the \a item. 280 281 The weight is relative to all other items in the layout, and determines how 282 the available space is distributed over the items in the layout. 283 284 \param item The item within this view that the weight applies to. 285 \param weight The weight of the item. 286 287 \since Haiku R1 288*/ 289 290 291/*! 292 \fn bool BSplitView::IsCollapsible(int32 index) const 293 \brief Get whether the item at \a index is collapsible. 294 295 \param index The index of the item (zero-based). 296 297 \retval true The user can collapse the item. 298 \retval false The user cannot collapse the item. 299 300 \since Haiku R1 301*/ 302 303 304/*! 305 \fn void BSplitView::SetCollapsible(bool collapsible) 306 \brief Set the whether all the layout items in this view are collapsible. 307 308 \param collapsible \c true if all items in this layout are collapsible, 309 \c false if they are not. 310 311 \since Haiku R1 312*/ 313 314 315/*! 316 \fn void BSplitView::SetCollapsible(int32 index, bool collapsible) 317 \brief Set whether the item at \a index is collapsible. 318 319 \param index The index of the item (zero-based). 320 \param collapsible \c true if the user may collaps the item, \c false if 321 they may not. 322 323 \since Haiku R1 324*/ 325 326 327/*! 328 \fn void BSplitView::SetCollapsible(int32 first, int32 last, bool collapsible) 329 \brief Set whether the items from \a first to \a last are collapsible. 330 331 \param first The index of the first item that you want the setting to apply 332 to (zero-based). 333 \param last The index of the last item that you want the setting to apply 334 to (zero-based). 335 \param collapsible \c true if the user may collaps the item, \c false if 336 they may not. 337 338 \since Haiku R1 339*/ 340 341 342/*! 343 \fn bool BSplitView::IsItemCollapsed(int32 index) const 344 \brief Check whether the item at \a index is collapsed. 345 346 \param index The index of the item (zero-based). 347 348 \retval true The item is collapsed. 349 \retval false The item is not collapsed. 350 351 \since Haiku R1 352*/ 353 354 355/*! 356 \fn void BSplitView::SetItemCollapsed(int32 index, bool collapsed) 357 \brief Set whether the item at \a index is displayed as collapsed. 358 359 \param index The index of the item (zero-based). 360 \param collapsed \c true if the item should be rendered collapsed, \c 361 false if it needs to be visible. 362 363 \since Haiku R1 364*/ 365 366 367/*! 368 \fn void BSplitView::AddChild(BView *child, BView *sibling=NULL) 369 \brief Add a \a child to the view. 370 371 Passthrough for \ref BView::AddChild(BView *child, BView *sibling). This 372 bypasses the layout system, so only use it when you know what you are 373 doing. 374 375 \since Haiku R1 376*/ 377 378 379/*! 380 \fn bool BSplitView::AddChild(BView *child, float weight) 381 \brief Add a \a child with a \a weight. 382 383 The view will be added at the end of the existing layout items, meaning it 384 will be placed to the right or bottom of existing items. 385 386 \param child The view that should be added as a child. The ownership is 387 transferred to this view. 388 \param weight The weight of the item. 389 390 \return \c true when succesfully, \c false if there was an error. 391 392 \since Haiku R1 393*/ 394 395 396/*! 397 \fn bool BSplitView::AddChild(int32 index, BView *child, float weight) 398 \brief Add a \a child at \a index with a \a weight. 399 400 \param index The desired position for the \a child. Existing items will be 401 shifted to the right or down based on the orientation. If the index is 402 higher than the number of items, the item will be added after farmost 403 item. The index is zero-based. 404 \param child The view that should be added as a child. The ownership is 405 transferred to this view. 406 \param weight The weight of the item. 407 408 \return \c true when succesfully, \c false if there was an error. 409 410 \since Haiku R1 411*/ 412 413 414/*! 415 \fn bool BSplitView::AddChild(BLayoutItem *child) 416 \brief Add a \a child. 417 418 The child will be added at the end of the existing layout items, meaning it 419 will be placed to the right or bottom of existing items. 420 421 \param child The layout item to add. 422 423 \return \c true when succesfully, \c false if there was an error. 424 425 \since Haiku R1 426*/ 427 428 429/*! 430 \fn bool BSplitView::AddChild(BLayoutItem *child, float weight) 431 \brief Add a \a child with a \a weight. 432 433 The child will be added at the end of the existing layout items, meaning it 434 will be placed to the right or bottom of existing items. 435 436 \param child The layout item to add. 437 \param weight The weight of the item. 438 439 \return \c true when succesfully, \c false if there was an error. 440 441 \since Haiku R1 442*/ 443 444 445/*! 446 \fn bool BSplitView::AddChild(int32 index, BLayoutItem *child, float weight) 447 \brief Add a \a child at \a index with a \a weight. 448 449 \param index The desired position for the \a child. Existing items will be 450 shifted to the right or down based on the orientation. If the index is 451 higher than the number of items, the item will be added after farmost 452 item. The index is zero-based. 453 \param child The layout item to add. 454 \param weight The weight of the item. 455 456 \return \c true when succesfully, \c false if there was an error. 457 458 \since Haiku R1 459*/ 460 461 462/*! 463 \fn virtual virtual void BSplitView::AttachedToWindow() 464 \brief Hook method overridden from BView. 465 466 \since Haiku R1 467*/ 468 469 470/*! 471 \fn virtual virtual void BSplitView::Draw(BRect updateRect) 472 \brief Hook method overridden from BView. 473 474 \since Haiku R1 475*/ 476 477 478/*! 479 \fn virtual virtual void BSplitView::DrawAfterChildren(BRect updateRect) 480 \brief Hook method overridden from BView. 481 482 \since Haiku R1 483*/ 484 485 486/*! 487 \fn virtual virtual void BSplitView::MouseDown(BPoint where) 488 \brief Hook method overridden from BView. 489 490 \since Haiku R1 491*/ 492 493 494/*! 495 \fn virtual virtual void BSplitView::MouseUp(BPoint where) 496 \brief Hook method overridden from BView. 497 498 \since Haiku R1 499*/ 500 501 502/*! 503 \fn virtual virtual void BSplitView::MouseMoved(BPoint where, uint32 transit, const BMessage *message) 504 \brief Hook method overridden from BView. 505 506 \since Haiku R1 507*/ 508 509 510/*! 511 \fn virtual virtual void BSplitView::MessageReceived(BMessage *message) 512 \brief Hook method overridden from BView. 513 514 \since Haiku R1 515*/ 516 517 518/*! 519 \fn virtual virtual void BSplitView::SetLayout(BLayout *layout) 520 \brief Hook method overridden from BView. 521 522 \since Haiku R1 523*/ 524 525 526/*! 527 \fn virtual virtual status_t BSplitView::Archive(BMessage *into, bool deep=true) const 528 \copydoc BArchivable::Archive() 529*/ 530 531 532/*! 533 \fn virtual virtual status_t BSplitView::Perform(perform_code d, void *arg) 534 \brief Hook method overridden from BView. 535 536 \since Haiku R1 537*/ 538 539 540/*! 541 \fn static static BArchivable* BSplitView::Instantiate(BMessage *from) 542 \brief Instantiate the view from the message \a from. 543 544 \since Haiku R1 545*/ 546 547 548/*! 549 \fn virtual virtual status_t BSplitView::AllArchived(BMessage *into) const 550 \brief Hook method overridden from BArchivable. 551 552 \since Haiku R1 553*/ 554 555 556/*! 557 \fn virtual virtual status_t BSplitView::AllUnarchived(const BMessage *from) 558 \brief Hook method overridden from BArchivable. 559 560 \since Haiku R1 561*/ 562 563 564/*! 565 \fn virtual virtual void BSplitView::DrawSplitter(BRect frame, const BRect &updateRect, orientation orientation, bool pressed) 566 \brief Hook method called when the splitter needs to be drawn. 567 568 This method is called in the context of a \ref BView::Draw() operation. 569 Derived classes can override this to draw a splitter. 570 571 \since Haiku R1 572*/ 573
