1/* 2 * Copyright 2014 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * John Scipione, jscipione@gmail.com 7 * 8 * Corresponds to: 9 * headers/os/interface/StringView.h hrev48439 10 * src/kits/interface/StringView.cpp hrev48439 11 */ 12 13 14/*! 15 \file StringView.h 16 \ingroup interface 17 \ingroup libbe 18 \brief BStringView class definition. 19*/ 20 21 22/*! 23 \class BStringView 24 \ingroup interface 25 \ingroup libbe 26 \brief Draws a non-editable single-line text string, 27 most commonly used as a label. 28 29 \since BeOS R3 30*/ 31 32 33/*! 34 \fn BStringView::BStringView(BRect frame, const char* name, const char* text, 35 uint32 resizingMode, uint32 flags) 36 \brief Creates a new BStringView object which displays the non-editable 37 \a text string in the plain system font (\c be_plain_font). 38 39 \param frame The frame rectangle to draw the string view into. 40 \param name The string view's \a name. Can be \c NULL. 41 \param text The string view's label \a text. Can be \c NULL. 42 \param resizingMode Sets the parameters by which the BStringView can be 43 resized. See BView for more information on resizing options. 44 \param flags The \a flags mask sets what notifications the BStringView can 45 receive. See BView for more information on \a flags. 46 \c B_FULL_UPDATE_ON_RESIZE is always set. 47 48 In order to prevent the string from being truncated the frame rectangle 49 must be large enough to display the entire string in the current font. 50 The string is drawn at the bottom of the frame rectangle and by default 51 is left-aligned, call SetAlignment() to set a different horizontal 52 alignment. 53 54 You may also change the font variety used by calling SetFont(). 55 56 \see SetAlignment() 57 \see SetFont() 58 59 \since BeOS R3 60*/ 61 62 63/*! 64 \fn BStringView::BStringView(const char* name, const char* text, uint32 flags) 65 \brief Layout constructor. 66 67 \param name The string view's \a name. Can be \c NULL. 68 \param text The string view's label \a text. Can be \c NULL. 69 \param flags The \a flags mask sets what notifications the BStringView can 70 receive. See BView for more information on \a flags. 71 \c B_FULL_UPDATE_ON_RESIZE is always set. 72 73 The string is left-aligned by default. There are two ways to set the 74 horizontal alignment of the string view. The preferred method is to call 75 BLayoutItem::SetExplicitAlignment() or you may also call SetAlignment(). 76 77 You may also change the font variety used by calling SetFont(). 78 79 \see BLayoutItem::SetExplicitAlignment() 80 \see SetAlignment() 81 \see SetFont() 82 83 \since Haiku R1 84*/ 85 86 87/*! 88 \fn BStringView::BStringView(BMessage* archive) 89 \brief Archive constructor. 90 91 \warning This method is usually not called directly. If you want to build 92 a string view from an archive message you should call 93 Instantiate() instead which can handle errors properly. 94 95 \param archive The message \a archive to construct the string view from. 96 97 \since BeOS R3 98*/ 99 100 101/*! 102 \fn BStringView::~BStringView() 103 \brief Destructor method, frees the memory used by the string view. 104 105 \since BeOS R3 106*/ 107 108 109/*! 110 \name Archiving 111*/ 112 113 114//! @{ 115 116 117/*! 118 \fn BArchivable* BStringView::Instantiate(BMessage* archive) 119 \brief Creates a new BStringView object from an \a archive message. 120 121 The string view's text, and alignment can be set using this method. 122 - The "_text" property is a \c B_STRING_TYPE containing the text of 123 the string view. 124 - The "_align" property is a \c B_INT32_TYPE containing the string 125 view's alignment flag. This should be casted to an alignment type. 126 Choices are: 127 - \c B_ALIGN_LEFT 128 - \c B_ALIGN_RIGHT 129 - \c B_ALIGN_CENTER 130 131 \return A newly created BStringView object or \c NULL if the message 132 doesn't contain an archived BStringView. 133 134 \since BeOS R3 135*/ 136 137 138/*! 139 \fn status_t BStringView::Archive(BMessage* archive, bool deep) const 140 \brief Archives the the BStringView object into the \a archive message. 141 142 \param archive A pointer to the BMessage to archive the object into. 143 \param deep This parameter has no effect for this class. 144 145 \return A status code, \c B_OK if everything went well or an error code 146 otherwise. 147 \retval B_OK The object was archived successfully. 148 \retval B_NO_MEMORY Ran out of memory while archiving the object. 149 150 \since BeOS R3 151*/ 152 153 154//! @} 155 156 157/*! 158 \name Hook methods 159*/ 160 161 162//! @{ 163 164 165/*! 166 \fn void BStringView::AttachedToWindow() 167 \brief Hook method called when the BStringView is attached to a window. 168 169 The view color is set to either the parent's view color or 170 \c B_TRANSPARENT_COLOR if the string view isn't attached to a view. 171 172 \sa BView::AttachedToWindow() 173 174 \since BeOS R3 175*/ 176 177 178/*! 179 \fn void BStringView::DetachedFromWindow() 180 \brief Hook method called when the BStringView is detached from a window. 181 182 \copydetails BView::DetachedFromWindow() 183*/ 184 185 186/*! 187 \fn void BStringView::AllAttached() 188 \brief Similar to AttachedToWindow() but this method is triggered after 189 all child views have already been attached to a window. 190 191 \copydetails BView::AllAttached() 192*/ 193 194 195/*! 196 \fn void BStringView::AllDetached() 197 \brief Similar to AttachedToWindow() but this method is triggered after 198 all child views have already been detached from a window. 199 200 \copydetails BView::AllDetached() 201*/ 202 203 204/*! 205 \fn void BStringView::Draw(BRect updateRect) 206 \brief Draws the area of the view that intersects \a updateRect. 207 208 \remark This is an hook method called by the Interface Kit, you don't have to 209 call it yourself. If you need to forcefully redraw the view consider 210 calling Invalidate() instead. 211 212 \param updateRect The rectangular area to be drawn. 213 214 \since BeOS R3 215 216 \see BView::Draw() 217*/ 218 219 220/*! 221 \fn void BStringView::FrameMoved(BPoint newPosition) 222 \brief Hook method called when the string view is moved. 223 224 \copydetails BView::FrameMoved() 225*/ 226 227 228/*! 229 \fn void BStringView::FrameResized(float newWidth, float newHeight) 230 \brief Hook method called when the string view is resized. 231 232 \copydetails BView::FrameResized() 233*/ 234 235 236/*! 237 \fn void BStringView::MessageReceived(BMessage* message) 238 \brief Handle \a message received by the associated looper. 239 240 \copydetails BView::MessageReceived() 241*/ 242 243 244/*! 245 \fn void BStringView::MouseDown(BPoint where) 246 \brief Hook method called when a mouse button is pressed. 247 248 \copydetails BView::MouseDown() 249*/ 250 251 252/*! 253 \fn void BStringView::MouseMoved(BPoint where, uint32 code, 254 const BMessage* dragMessage) 255 \brief Hook method called when the mouse is moved. 256 257 \copydetails BView::MouseMoved() 258*/ 259 260 261/*! 262 \fn void BStringView::MouseUp(BPoint where) 263 \brief Hook method called when a mouse button is released. 264 265 \copydetails BView::MouseUp() 266*/ 267 268 269//! @} 270 271 272/*! 273 \fn void BStringView::MakeFocus(bool focus) 274 \brief Makes the string view the current focus view of the window or 275 gives up being the window's focus view. 276 277 \copydetails BView::MakeFocus() 278*/ 279 280 281/*! 282 \fn void BStringView::GetPreferredSize(float* _width, float* _height) 283 \brief Fills out the preferred width and height of the string view 284 into the \a _width and \a _height parameters respectively. 285 286 \copydetails BView::GetPreferredSize() 287*/ 288 289 290/*! 291 \fn BSize BStringView::MinSize() 292 \brief Returns the string view's minimum size. 293 294 \copydetails BView::MinSize() 295*/ 296 297 298/*! 299 \fn BSize BStringView::MaxSize() 300 \brief Returns the string view's maximum size. 301 302 \copydetails BView::MaxSize() 303*/ 304 305 306/*! 307 \fn BSize BStringView::PreferredSize() 308 \brief Returns the string view's preferred size. 309 310 \copydetails BView::PreferredSize() 311*/ 312 313 314/*! 315 \fn void BStringView::ResizeToPreferred() 316 \brief Resize the string view to its preferred size. 317 318 \copydetails BView::ResizeToPreferred() 319*/ 320 321 322/*! 323 \fn BAlignment BStringView::LayoutAlignment() 324 \brief Returns the alignment used by this view as part of a BLayout. 325 326 \return The alignment used by this view as a BAlignment. 327 328 \since Haiku R1 329*/ 330 331 332/*! 333 \name Text methods 334*/ 335 336 337//! @{ 338 339 340/*! 341 \fn void BStringView::SetText(const char* text) 342 \brief Sets the \a text string displayed by the string view. 343 344 The \a text string is copied, BStringView does not take ownership 345 of the memory referenced by the pointer so you should free it yourself 346 afterwords. If a string has previously been set on the string view, the 347 memory used by the old string is freed before setting the new string. 348 349 \param text The \a text string to set. 350 351 \since BeOS R3 352*/ 353 354 355/*! 356 \fn const char* BStringView::Text() const 357 \brief Returns the text currently set on the string view. 358 359 \returns The string view's text as a const char*. 360 361 \since BeOS R3 362*/ 363 364 365//! @} 366 367 368/*! 369 \name Alignment methods 370*/ 371 372 373//! @{ 374 375 376/*! 377 \fn void BStringView::SetAlignment(alignment flag) 378 \brief Sets the way text is aligned within the view's frame. 379 380 Choices are: 381 - \c B_ALIGN_LEFT 382 - \c B_ALIGN_RIGHT 383 - \c B_ALIGN_CENTER 384 385 \remark For string views that are part of a BLayout consider 386 using BLayoutItem::SetExplicitAlignment() instead. 387 388 \param flag The text alignment to set. 389 390 \since BeOS R3 391*/ 392 393 394/*! 395 \fn alignment BStringView::Alignment() const 396 \brief Returns the currently set text alignment flag. 397 398 \return The current alignment flag. 399 400 \see SetAlignment() 401 402 \since BeOS R3 403*/ 404 405 406//! @} 407 408 409/*! 410 \fn BHandler* BStringView::ResolveSpecifier(BMessage* message, int32 index, 411 BMessage* specifier, int32 what, const char* property) 412 \copydoc BView::ResolveSpecifier() 413*/ 414 415 416/*! 417 \fn status_t BStringView::GetSupportedSuites(BMessage* message) 418 \copydoc BView::GetSupportedSuites() 419*/ 420 421 422/*! 423 \fn void BStringView::SetFont(const BFont* font, uint32 mask) 424 \brief Sets the font of the string view to \a font with the font 425 parameters set by \a mask. 426 427 \param font The \a font to set the string view to. 428 \param mask A \a mask indicating which properties of \a font to set. 429 430 \see BView::SetFont() 431 432 \since Haiku R1 433*/ 434 435 436/*! 437 \fn void BStringView::LayoutInvalidated(bool descendants) 438 \brief Hook method called when the layout is invalidated. 439 440 The default implementation invalidates the cached preferred size. 441 442 \copydetails BView::LayoutInvalidated(bool descendants) 443*/ 444 445 446/*! 447 \fn status_t BStringView::Perform(perform_code code, void* _data) 448 \brief Perform some action. (Internal Method) 449 450 \since Haiku R1 451*/ 452