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