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