docs/user/interface/StringView.dox

   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 */