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