1/* 2 * Copyright 2011 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Clark Gaeble 7 * Adrien Destugues <pulkomandy@pulkomandy.ath.cx> 8 * John Scipione <jscipione@gmail.com> 9 * 10 * Corresponds to: 11 * headers/os/interface/Box.h rev 42274 12 * src/kits/interface/Box.cpp rev 42274 13 */ 14 15 16/*! 17 \file Box.h 18 \ingroup interface 19 \ingroup libbe 20 \brief Defines the BBox class 21*/ 22 23 24/*! 25 \class BBox 26 \ingroup interface 27 \ingroup libbe 28 \brief A rectangular view with a border and an optional label to group 29 related subviews visually. 30 31 A basic BBox looks like this: 32 \image html B_FANCY_BORDER.png 33 34 A box's label can either be composed of text or it can be a view such 35 as a checkbox or dropdown box. See SetLabel() for more details on setting 36 the box's label. 37 38 \since BeOS R3 39*/ 40 41 42/*! 43 \fn BBox::BBox(BRect frame, const char *name = NULL, 44 uint32 resizingMode = B_FOLLOW_LEFT | B_FOLLOW_TOP, 45 uint32 flags = B_WILL_DRAW | B_FRAME_EVENTS | B_NAVIGABLE_JUMP, 46 border_style border = B_FANCY_BORDER) 47 \brief Constructs a named BBox object from a set of dimensions. 48 49 \note This is the only constructor that can be used if the box is to be 50 inserted in a window that doesn't use the layout system. 51 52 \param frame The bounds of the box. 53 \param name The name of the box. 54 \param resizingMode Defines the behavior of the box as the parent view 55 resizes. See BView for details. 56 \param flags Behavior flags for the box. See BView for details. 57 \param border The border_style of the box. 58 59 \since BeOS R3 60*/ 61 62 63/*! 64 \fn BBox::BBox(const char* name, 65 uint32 flags = B_WILL_DRAW | B_FRAME_EVENTS | B_NAVIGABLE_JUMP, 66 border_style border = B_FANCY_BORDER, BView* child = NULL) 67 \brief Constructs a named BBox object with its dimensions defined 68 automatically by the Layout API. 69 70 \param name The name of the box. 71 \param flags Behavior flags for the box. See BView for details. 72 \param border The border_style of the box. 73 \param child Adds an initial child to the Box object. See the Layout 74 API for details. 75 76 \since Haiku R1 77*/ 78 79 80/*! 81 \fn BBox::BBox(border_style border, BView* child) 82 \brief Constructs an anonymous BBox object with a defined border style 83 and child view. 84 85 There can only be a single child view. This view can, however, act as a 86 nesting container if you need to show more items inside the box. 87 88 \since Haiku R1 89*/ 90 91 92/*! 93 \fn BBox::BBox(BMessage* archive) 94 \brief Constructs a BBox object from an \a archive message. 95 96 This method is usually not called directly. If you want to build a BBox 97 object from a message you should call Instantiate() which can 98 handle errors properly. 99 100 If the \a archive deep, the BBox object will also unarchive each of its 101 child views recursively. 102 103 \param archive The \a archive message to restore from. 104 105 \since BeOS R3 106*/ 107 108 109/*! 110 \fn BBox::~BBox() 111 \brief Destructor method. 112 113 Calling the destructor will also free the memory used by the box's label 114 if it has one. 115 116 \since BeOS R3 117*/ 118 119 120/*! 121 \name Archiving 122*/ 123 124 125//! @{ 126 127 128/*! 129 \fn static BArchivable* BBox::Instantiate(BMessage* archive) 130 \brief Creates a new object from an \a archive. 131 132 If the message is a valid object then the instance created from the 133 passed in \a archive will be returned. Otherwise this method will 134 return \c NULL. 135 136 \param archive The \a archive message. 137 138 \returns An instance of the object if \a archive is valid or \c NULL. 139 140 \sa BArchivable::Instantiate() 141 142 \since BeOS R3 143*/ 144 145 146/*! 147 \fn virtual status_t BBox::Archive(BMessage* archive, 148 bool deep = true) const; 149 \brief Archives the object into \a archive. 150 151 \param archive The target \a archive that the data will go into. 152 \param deep Whether or not to recursively archive child views. 153 154 \retval B_OK The archive operation was successful. 155 \retval B_BAD_VALUE \c NULL \a archive message. 156 \retval B_ERROR The archive operation failed. 157 158 \sa BArchivable::Archive() 159 160 \since BeOS R3 161*/ 162 163 164//! @} 165 166 167/*! 168 \fn virtual void BBox::SetBorder(border_style border) 169 \brief Sets the #border_style. 170 171 Possible #border_style values include: 172 - \c B_PLAIN_BORDER A single 1-pixel line border. 173 - \c B_FANCY_BORDER The default, beveled look. 174 - \c B_NO_BORDER Used to make a borderless box. 175 176 \param border The #border_style to set. 177 178 \since BeOS R3 179*/ 180 181 182/*! 183 \fn border_style BBox::Border() const 184 \brief Gets the current #border_style. 185 186 Possible #border_style values include: 187 - \c B_PLAIN_BORDER A single 1-pixel line border. 188 - \c B_FANCY_BORDER The default, beveled look. 189 - \c B_NO_BORDER Used to make a borderless box. 190 191 \returns The #border_style of the box. 192 193 \since BeOS R3 194*/ 195 196 197/*! 198 \fn float BBox::TopBorderOffset() 199 \brief Gets the distance from the very top of the box to the top border 200 line in pixels. 201 202 \warning This method is not yet finalized. 203 204 The distance may vary depending on the text or view used as label and the 205 font settings. The border is drawn center-aligned with the label. This 206 method can be used to line up two boxes visually if one has a label and 207 the other does not. 208 209 \returns The distance from the very top of the box to the top border 210 line in pixels as a \c float. 211 212 \since Haiku R1 213*/ 214 215 216/*! 217 \fn BRect BBox::InnerFrame() 218 \brief Gets the frame rectangle just inside the border of the box. 219 220 \warning This method is not yet finalized. 221 222 \returns A BRect set to the dimensions of the box's inside border. 223 224 \since Haiku R1 225*/ 226 227 228/*! 229 \fn void BBox::SetLabel(const char* string) 230 \brief Sets the box's label text. 231 232 Below is an example of a box with some simple text label: 233 234 \image html BBox_example.png 235 236 The code to create a box with a text label looks like this: 237 \code 238fIconBox = new BBox("Icon Box"); 239fIconBox->SetLabel("Icon"); 240 \endcode 241 242 \param string The label text string to set as the box's title. 243 244 \since BeOS R3 245*/ 246 247 248/*! 249 \fn status_t BBox::SetLabel(BView* viewLabel) 250 \brief Sets the label from a BView. 251 252 This version of SetLabel() provides for building a BBox object with a 253 control used in place of the text label. You can pass in any type of 254 BView derived control for this such as a BPopupMenu or BCheckBox. 255 256 An example of a box with a checkbox view is shown below: 257 \image html BBox_with_checkbox.png 258 259 The code to create such a box looks like this: 260 \code 261fVirtualMemoryEnabledCheckBox = new BCheckBox("Virtual memory check box", 262 "Enable virtual memory", new BMessage(kVirtualMemoryEnabled)); 263 264BBox* fVirtualMemoryBox = new BBox("Virtual memory box"); 265fVirtualMemoryBox->SetLabel(fVirtualMemoryEnabledCheckBox); 266 \endcode 267 268 \param viewLabel A BView. 269 270 \returns \c B_OK 271 272 \since BeOS R3 273*/ 274 275 276/*! 277 \fn const char* BBox::Label() const 278 \brief Gets the text of the box's label. 279 280 This only works if the label is set as text. If you set the label to a 281 BView, you have to get the text by other means, likely starting with 282 LabelView. 283 284 \returns The label text of the BBox if the box has a text label or 285 \c NULL otherwise. 286 287 \since BeOS R3 288*/ 289 290 291/*! 292 \fn BView* BBox::LabelView() const 293 \brief Gets the BView representing the label. 294 295 \returns a pointer to a BView object. 296 297 \since BeOS R4 298*/ 299 300 301/*! 302 \fn virtual void BBox::Draw(BRect updateRect) 303 \brief Draws the area of the box that intersects \a updateRect. 304 305 This is an hook method called by the Interface Kit, you don't have to 306 call it yourself. If you need to forcefully redraw the view, 307 consider calling Invalidate() instead. 308 309 \param updateRect The rectangular area to be drawn. 310 311 \since BeOS R3 312*/ 313 314 315/*! 316 \fn virtual void BBox::AttachedToWindow() 317 \brief Hook method that is called when the object is attached to a 318 window. 319 320 This method overrides BView::AttachedToWindow() to set the background 321 color of the box to the background of its parent view. 322 323 If you are using the layout system, the BBox is also resized according to 324 the layout of the parent view. 325 326 \sa BView::AttachedToWindow() 327 328 \since BeOS R3 329*/ 330 331 332/*! 333 \fn virtual void BBox::FrameResized(float width, float height) 334 \brief Hook method that gets called when the BBox object is resized. 335 336 This method may be called either because the window in which the BBox 337 object was resized, or because the window layout was otherwise altered. 338 339 This method recomputes the layout of the BBox (including label and 340 contents) and makes it redraw as necessary. 341 342 \since BeOS R3 343*/ 344 345 346/*! 347 \fn virtual void BBox::ResizeToPreferred() 348 \brief Resizes the box to its preferred dimensions. 349 350 \note This only works in the non-layout mode, as it forces the resizing. 351 352 \since BeOS R3 353*/ 354 355 356/*! 357 \fn virtual void BBox::GetPreferredSize(float* _width, float* _height) 358 \brief Fill out the preferred width and height of the box 359 into the \a _width and \a _height parameters. 360 361 \note Either the \a _width or \a _height parameter may be set to \c NULL 362 if you only want to get the other one. 363 364 The size is computed from the child view sizes, unless it was explicitly 365 set for the BBox (which can be done only if the BBox is configured to 366 use the Layout API). 367 368 \param[out] _width Pointer to a \c float to store the width of the view. 369 \param[out] _height Pointer to a \c float to store the height of the view. 370 371 \since BeOS R3 372*/ 373 374 375/*! 376 \fn virtual BSize BBox::MinSize() 377 \brief Gets the minimum possible size of the BBox object. 378 379 Drawing the box at this size ensures the label and the child view are 380 visible. Reducing the size even more would mean that a view would not 381 be visible. 382 383 \since Haiku R1 384*/ 385 386 387/*! 388 \fn virtual BSize BBox::MaxSize() 389 \brief Gets the maximum possible size of the BBox object. 390 391 The maximum size depends on the maximize size of the child views. 392 393 \returns The maximum possible size of the BBox as a BSize. 394 395 \since Haiku R1 396*/ 397 398 399/*! 400 \fn virtual BSize BBox::PreferredSize() 401 \brief Returns the preferred size of the box. 402 403 This method works the same as GetPreferredSize, but uses the more 404 convenient BSize object. 405 406 \returns The minimum possible size of the BBox as a BSize. 407 408 \since Haiku R1 409*/ 410 411 412/*! 413 \fn virtual void BBox::DoLayout() 414 \brief Lays out the box moving everything into its appropriate position. 415 416 This only works if the BBox object was constructed using the Layout API, 417 i.e. it was created with one of the BRect-less constructors. 418 419 Once the size of the box is known from laying out its parent views, 420 this method is called so the box can adjust the position and size of the 421 label, eventually truncating the label text if there is not enough space. 422 The exact border positions are also computed, then the child view is also 423 laid out if its size constraints change. 424 425 \since Haiku R1 426*/ 427
