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 * Corresponds to: 9 * /trunk/headers/os/interface/Box.h rev 39685 10 * /trunk/src/kits/interface/Box.cpp rev 39685 11 12/*! 13\file Box.h 14\brief Defines the BBox class 15*/ 16 17/*! \class BBox 18 \ingroup interface 19 \brief Class just drawing a square box with a label in a window. 20 21 A Box represents a square on the interface with dimensions, an optional 22 name, and no interactivity. 23 24 This would be used to visually group elements together. 25*/ 26 27/*! \fn BBox::BBox(BRect frame, const char *name = NULL, uint32 resizingMode = B_FOLLOW_LEFT | B_FOLLOW_TOP, uint32 flags = B_WILL_DRAW | B_FRAME_EVENTS | B_NAVIGABLE_JUMP, border_style border = B_FANCY_BORDER) 28 \brief Constructs a Box from a set of dimensions. 29 30 This is the only constructor that can be used if the box is to be inserted 31 in a window that doesn't use the layout system. 32 33 \param frame The bounds of the box. 34 \param name The name of the box. 35 \param resizingMode Defines the behavior of the box as the parent view 36 resizes. 37 \param flags Behavior flags for the box. See BView page for more 38 info. 39 \param border Sets the initial style of the border. See SetBorder for 40 more details. 41*/ 42 43 44/*! \fn BBox::BBox(const char* name, uint32 flags = B_WILL_DRAW | B_FRAME_EVENTS | B_NAVIGABLE_JUMP, border_style border = B_FANCY_BORDER, BView* child = NULL) 45 \brief Constructs a named Box, with dimensions defined automatically by the 46 Layout Kit. 47 48 \param name The name of the box. 49 \param flags Behavior flags for the box. 50 \param border Defines the initial border style. 51 \param child Adds an initial child to the box. See: Layout Kit 52*/ 53 54 55/*! \fn BBox::BBox(border_style border, BView* child) 56 \brief Constructs an anonymous Box, with a defined border style and a child. 57 58 There can only be a single child view in the box. This view can, however, 59 act as a nesting container if you need more things to show inside the box. 60 61 \param border The initial border style of the box. 62 \param child The child of the Box. 63*/ 64 65 66/*! \fn BBox::BBox(BMessage* archive) 67 \brief For archive restoration, allows a box to be constructed from an 68 archive message. 69 70 You don't usually call this directly, if you want to build a BBox from a 71 message, prefer calling Instantiate, which can properly handle errors. 72 73 If the archive is a deep one, the box will also unarchive all of its 74 children recursively. 75 76 \param archive The archive to restore from. 77*/ 78 79 80/*! \fn static BArchivable* BBox::Instantiate(BMessage* archive) 81 \brief Creates a new BBox from an archive. 82 83 If the message is a valid box, an instance of BBox (created from the 84 archive) will be returned. Otherwise, this function will return NULL. 85*/ 86 87 88/*! \fn virtual status_t BBox::Archive(BMessage* archive, bool deep = true) const; 89 \brief Archives the box into archive. 90 91 \param archive The target archive which the box data will go into. 92 \param deep Whether or not to recursively archive the children. 93 \returns B_OK if the archive was successful. 94*/ 95 96 97/*! \fn virtual void BBox::SetBorder(border_style border) 98 \brief Sets the border style. 99 100 Possible values are B_PLAIN_BORDER (a single 1-pixel line border), 101 B_FANCY_BORDER (the default, slightly beveled look), and B_NO_BORDER, which 102 is used to make an invisible box. 103*/ 104 105 106/*! \fn border_style BBox::Border() const 107 \brief Gets the border style. 108*/ 109 110 111/*! \fn float BBox::TopBorderOffset() 112 \brief Gets the distance from the very top of the Box to the top border 113 line, in pixels. 114 115 The distance may vary depending on the text or view used as label, and the 116 font settings. The border is drawn center aligned with the label. 117 118 You can use this value to line up two boxes visually, if one has a label and 119 the other has not. 120*/ 121 122 123/*! \fn BRect BBox::InnerFrame() 124 \brief Returns the rectangle just inside the border. 125*/ 126 127 128/*! \fn void BBox::SetLabel(const char* string) 129 \brief Sets the label's text. 130 131 This text is shown as the box title on screen, so the user can identify the 132 purpose of it. 133*/ 134 135 136/*! \fn status_t BBox::SetLabel(BView* viewLabel) 137 \brief Sets the label from a pre-existing BView. 138 139 You can use any type of BView for this, such as a BPopupMenu. 140 This version of SetLabel is much more powerful than 141 SetLabel(const char* string). It allows building a box which contents can 142 be changed depending on the label widget. 143*/ 144 145 146/*! \fn const char* BBox::Label() const 147 \brief Gets the label's text. 148 149 This only works if the label was set as text. If you set another view as the 150 label, you have to get its text by other means, likely starting with 151 LabelView. 152*/ 153 154 155/*! \fn BView* BBox::LabelView() const 156 \brief Gets the BView representing the label. 157*/ 158 159 160/*! \fn virtual void BBox::Draw(BRect updateRect) 161 \brief Draws onto the parent window the part of the box that intersects 162 the dirty area. 163 164 This is an hook function called by the interface kit. You don't have to call 165 it yourself. If you need to force redrawing of (part of) the box, consider 166 using Invalidate instead. 167 168 \param updateRect The area that needs to be redrawn. Note the box may draw 169 more around the rectangle. 170*/ 171 172 173/*! \fn virtual void BBox::AttachedToWindow() 174 \brief Hook called when the box is attached to a window. 175 176 This function sets the box background color to the parent's one. 177 178 If you are using the layout system, the box is also resized depending 179 on the layout of the parent view. 180*/ 181 182 183/*! \fn virtual void BBox::FrameResized(float width, float height) 184 \brief Called when the box needs to change its size. 185 186 This function may be called either because the window in which the box is 187 was resized, or because the window layout was otherwise altered. 188 189 It recomputes the layouting of the box (including label and contents) and 190 makes it redraw itself as needed. 191*/ 192 193 194/*! \fn virtual void BBox::ResizeToPreferred() 195 \brief Resizes the box to its preferred dimensions. 196 197 This only works in the non-layout mode, as it forces the resizing. 198*/ 199 200 201/*! \fn virtual void BBox::GetPreferredSize(float* _width, float* _height) 202 \brief Gets the dimensions the box would prefer to be. 203 204 The size is computed from the children sizes, unless it was explicitly set 205 for the box (which canbe done only in layouted mode). 206 207 \note Either one of the parameters may be set to NULL if you only want to 208 get the other one. 209 210 \param _width An output parameter. The width of the preferred size is 211 placed in here. 212 \param _height An output parameter. The height of the preferred size is 213 placed in here. 214*/ 215 216 217/*! \fn virtual BSize BBox::MinSize() 218 \brief Gets the minimum possible size of the Box. 219 220 Drawing the box at this size ensures the label and the child view are 221 visible. Going smaller means something may get invisible on screen for lack 222 of space. 223*/ 224 225 226/*! \fn virtual BSize BBox::MaxSize() 227 \brief Gets the maximum possible size of the Box. 228 229 The maximum size depends on the child view's one. 230*/ 231 232 233/*! \fn virtual BSize BBox::PreferredSize() 234 \brief Returns the box's preferred size. 235 236 This is the same as GetPreferredSize, but using the more convenient BSize 237 struct. 238*/ 239 240 241/*! \fn virtual void BBox::DoLayout() 242 \brief Lays out the box. Moves everything to its appropriate position. 243 244 This only works if the box uses the layout system, ie., was created with 245 one of the BRect-less constructors. 246 247 Once the size of the box is known, from layouting of the parent views, this 248 function is called so the box can adjust the position and size of the label, 249 eventually truncating the text if there is not enough space. The exact 250 border positions are also computed, then the child view is also layouted if 251 its size constraints changed. 252*/ 253