docs/user/interface/TextControl.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/TextControl.h      hrev48527
  10  *              src/kits/interface/TextControl.cpp      hrev48527
  11  */
  12
  13
  14 /*!
  15         \file TextControl.h
  16         \ingroup interface
  17         \ingroup libbe
  18         \brief Provides the BTextControl class.
  19 */
  20
  21
  22 /*!
  23         \class BTextControl
  24         \ingroup interface
  25         \ingroup libbe
  26         \brief Displays a labeled text view control.
  27
  28         \since BeOS R3
  29 */
  30
  31
  32 /*!
  33         \fn BTextControl::BTextControl(BRect frame, const char* name, const char* label,
  34                 const char* text, BMessage* message, uint32 resizeMask, uint32 flags)
  35         \brief Creates a new BTextControl object.
  36
  37         \param frame The frame rectangle of the control.
  38         \param name The (internal) name of the control.
  39         \param label The control's \a label text.
  40         \param text The initial \a text content of the control.
  41         \param message The \a message to send to the control's target in response
  42                to a change.
  43         \param resizeMask Resizing mask, passed to BView.
  44         \param flags \a flags passed to BView.
  45
  46         \since BeOS R3
  47 */
  48
  49
  50 /*!
  51         \fn BTextControl::BTextControl(const char* name, const char* label,
  52                 const char* text, BMessage* message, uint32 flags)
  53         \brief Creates a new BTextControl object for use in a BLayout.
  54
  55         \param name The name of the object.
  56         \param label The control's \a label text.
  57         \param text The initial \a text content of the control.
  58         \param message The \a message to send to the control's target in response
  59                to a change.
  60         \param flags \a flags passed to BView.
  61
  62         \since Haiku R1
  63 */
  64
  65
  66 /*!
  67         \fn BTextControl::BTextControl(const char* label, const char* text,
  68                 BMessage* message)
  69         \brief Creates a new BTextControl object, dynamic layout version.
  70
  71         \param label The control's \a label text.
  72         \param text The initial \a text content of the control.
  73         \param message The \a message to send to the control's target in response
  74                to a change.
  75
  76         \since Haiku R1
  77 */
  78
  79
  80 /*!
  81         \fn BTextControl::BTextControl(BMessage* archive)
  82         \brief Creates a BTextControl object from the passed in \a archive.
  83
  84         \param archive The BMessage object from which the object is created.
  85
  86         \since BeOS R3
  87 */
  88
  89
  90 /*!
  91         \fn BTextControl::~BTextControl()
  92         \brief Frees the memory allocated and destroys the object.
  93
  94         \since BeOS R3
  95 */
  96
  97
  98 /*!
  99         \name Archiving
 100 */
 101
 102
 103 //! @{
 104
 105
 106 /*!
 107         \fn BArchivable* BTextControl::Instantiate(BMessage* archive)
 108         \brief Instantiates a BTextControl object from the passed in \a archive.
 109
 110         \param archive The BMessage object that the object is created from.
 111
 112         \return A new BTextControl object as a BArchivable.
 113
 114         \since BeOS R3
 115 */
 116
 117
 118 /*!
 119         \fn status_t BTextControl::Archive(BMessage* data, bool deep) const
 120         \brief Archives the object into the \a data message.
 121
 122         - The label is stored in \c _a_label
 123         - The text is stored in \c _a_text
 124         - The current divider position is stored in \c _divide
 125           (ignored in the BLayout version)
 126         - The modification message is stored in \c _mod_msg
 127
 128         \param data A pointer to the BMessage object to archive the object into.
 129         \param deep Whether or not to archive child controls as well.
 130
 131         \return A status code, \c B_OK if everything went well or an error code
 132                 otherwise.
 133         \retval B_OK The object was archived.
 134         \retval B_NO_MEMORY Ran out of memory while archiving the object.
 135
 136         \since BeOS R3
 137 */
 138
 139
 140 /*!
 141         \fn status_t BTextControl::AllArchived(BMessage* into) const
 142         \brief Hook method called when all views have been archived.
 143
 144         \copydetails BView::AllArchived()
 145 */
 146
 147
 148 /*!
 149         \fn status_t BTextControl::AllUnarchived(const BMessage* from)
 150         \brief Hook method called when all views have been unarchived.
 151
 152         \copydetails BView::AllUnarchived()
 153 */
 154
 155
 156 //! @}
 157
 158
 159 /*!
 160         \name Hook Methods
 161 */
 162
 163
 164 //! @{
 165
 166
 167 /*!
 168         \fn void BTextControl::AllAttached()
 169         \brief Similar to AttachedToWindow() but this method is triggered after
 170                all child views have already been attached to a window.
 171
 172         \since BeOS R3
 173 */
 174
 175
 176 /*!
 177         \fn void BTextControl::AllDetached()
 178         \brief Similar to AttachedToWindow() but this method is triggered after
 179                all child views have already been detached from a window.
 180
 181         \since BeOS R3
 182 */
 183
 184
 185 /*!
 186         \fn void BTextControl::AttachedToWindow()
 187         \brief Sets the font color to \c B_DOCUMENT_TEXT_COLOR and the view and
 188                low colors to \c B_DOCUMENT_BACKGROUND_COLOR.
 189
 190         If the control is disabled, the font, view, and low colors are set to
 191         \c B_PANEL_BACKGROUND_COLOR is tinted to show a disabled text color and
 192         background instead.
 193
 194         \since BeOS R3
 195 */
 196
 197
 198 /*!
 199         \fn void BTextControl::DetachedFromWindow()
 200         \brief Hook method called when the object is detached from a window.
 201
 202         \since BeOS R3
 203 */
 204
 205
 206 /*!
 207         \fn void BTextControl::Draw(BRect updateRect)
 208         \brief Hook method called to draw the contents of the text control.
 209
 210         \param updateRect The rectangular area to draw.
 211
 212         \since BeOS R3
 213 */
 214
 215
 216 /*!
 217         \fn void BTextControl::FrameMoved(BPoint newPosition)
 218         \brief Hook method called when the control position is moved.
 219
 220         \param newPosition The point of the top left corner of the frame
 221                that the view has been moved to.
 222
 223         \since BeOS R3
 224 */
 225
 226
 227 /*!
 228         \fn void BTextControl::FrameResized(float newWidth, float newHeight)
 229         \brief Hook method that is called when the control position is resized.
 230
 231         This method updates only the parts of the frame that changed.
 232
 233         \param newWidth The new width of the control.
 234         \param newHeight The new height of the control.
 235
 236         \since BeOS R3
 237 */
 238
 239
 240 /*!
 241         \fn status_t BTextControl::Invoke(BMessage* message)
 242         \brief Sends a copy of the model \a message to the designated target.
 243
 244         \copydetails BControl::Invoke()
 245 */
 246
 247
 248 /*!
 249         \fn void BTextControl::LayoutInvalidated(bool descendants)
 250         \brief Hook method called when the layout is invalidated.
 251
 252         \param descendants Whether or not child views have also been invalidated.
 253
 254         \since Haiku R1
 255 */
 256
 257
 258 /*!
 259         \fn void BTextControl::MessageReceived(BMessage* message)
 260         \brief Handle \a message received by the associated looper.
 261
 262         \copydetails BView::MessageReceived()
 263 */
 264
 265
 266 /*!
 267         \fn void BTextControl::MouseDown(BPoint where)
 268         \brief Hook method that is called when a mouse text control is pushed down while
 269                the cursor is contained in the control.
 270
 271         Focuses the text control.
 272
 273         \since BeOS R3
 274 */
 275
 276
 277 /*!
 278         \fn void BTextControl::MouseMoved(BPoint where, uint32 code,
 279                 const BMessage* dragMessage)
 280         \brief Hook method called when the mouse is moved.
 281
 282         \copydetails BControl::MouseMoved()
 283 */
 284
 285
 286 /*!
 287         \fn void BTextControl::MouseUp(BPoint where)
 288         \brief Hook method called when a mouse button is released.
 289
 290         \copydetails BControl::MouseUp()
 291 */
 292
 293
 294 /*!
 295         \fn void BTextControl::WindowActivated(bool active)
 296         \brief Hook method that is called when the window becomes the active window
 297                or gives up that status.
 298
 299         Redraw focus indicator and notify the text view.
 300
 301         \copydetails BView::WindowActivated()
 302 */
 303
 304
 305 //! @}
 306
 307
 308 /*!
 309         \fn void BTextControl::SetText(const char* text)
 310         \brief Sets the text displayed by the BTextControl.
 311
 312         \since BeOS R3
 313 */
 314
 315
 316 /*!
 317         \fn const char* BTextControl::Text() const
 318         \brief Returns the text displayed by the BTextControl.
 319
 320         \since BeOS R3
 321 */
 322
 323
 324 /*!
 325         \fn void BTextControl::MarkAsInvalid(bool invalid)
 326         \brief Sets or removes the invalid flag.
 327
 328         \since Haiku R1
 329 */
 330
 331
 332 /*!
 333         \fn void BTextControl::SetValue(int32 value)
 334         \brief Calls BControl::SetValue(). This isn't particularly useful.
 335
 336         \copydetails BControl::SetValue()
 337 */
 338
 339
 340 /*!
 341         \fn BTextView* BTextControl::TextView() const
 342         \brief Returns a pointer to the TextView object.
 343
 344         \since BeOS R3
 345 */
 346
 347
 348 /*!
 349         \fn void BTextControl::SetModificationMessage(BMessage* message)
 350         \brief Assigns \a message to the control, freeing the previously
 351                assigned message.
 352
 353         Passing NULL deletes the current modification message without replacing it.
 354
 355         \since BeOS R3
 356 */
 357
 358
 359 /*!
 360         \fn BMessage* BTextControl::ModificationMessage() const
 361         \brief Returns the control's modification message.
 362 */
 363
 364
 365 /*!
 366         \fn void BTextControl::SetAlignment(alignment labelAlignment,
 367                 alignment textAlignment)
 368         \brief Set the alignment of the label and the text within the control.
 369
 370         The default is \c B_ALIGN_LEFT for both label and text.
 371
 372         \since BeOS R3
 373 */
 374
 375
 376 /*!
 377         \fn void BTextControl::GetAlignment(alignment* _label,
 378                 alignment* _text) const
 379         \brief Fills out the label and text alignments into \a _label and \a text.
 380
 381         \since BeOS R3
 382 */
 383
 384
 385 /*!
 386         \fn void BTextControl::SetDivider(float position)
 387         \brief Sets the horizontal \a position of the divider that separates the
 388                label from the text view.
 389
 390         \remark It is not recommended to use this method for text control that are
 391                 part of a BLayout. Instead split the label and text view into
 392                 separate layout items using CreateLabelLayoutItem() and
 393                 CreateTextViewLayoutItem(). This allows you to have better control
 394                 over the position of the label and text view portions of your
 395                 text control.
 396
 397         \param position The divider \a position to set, should be an integral value.
 398
 399         \since BeOS R3
 400 */
 401
 402
 403 /*!
 404         \fn float BTextControl::Divider() const
 405         \brief Returns the current divider position.
 406
 407         \since BeOS R3
 408 */
 409
 410
 411 /*!
 412         \fn void BTextControl::MakeFocus(bool focus)
 413         \brief Passes MakeFocus() to the child BTextView.
 414
 415         \since BeOS R3
 416 */
 417
 418
 419 /*!
 420         \fn void BTextControl::SetEnabled(bool enable)
 421         \brief Enables or disables the text control.
 422
 423         \param enable \c true to enable the control, \c false to disable it.
 424
 425         \since R3
 426 */
 427
 428
 429 /*!
 430         \fn void BTextControl::GetPreferredSize(float* _width, float* _height)
 431         \brief Fills out \a _width and \a _height with the optimal width and
 432                height of the text control to display the label and the text
 433                respectively.
 434
 435         \since BeOS R3
 436 */
 437
 438
 439 /*!
 440         \fn void BTextControl::ResizeToPreferred()
 441         \brief Resizes the text control to its preferred size, keeping its left
 442                and top sides constant while adjusting the width and height of
 443                the text view.
 444
 445         \warning It is not recommended to use this method for text control that
 446                  are part of a BLayout.
 447
 448         \since BeOS R3
 449 */
 450
 451
 452 /*!
 453         \fn void BTextControl::SetFlags(uint32 flags)
 454         \brief Sets the control flags according to the \a flags mask.
 455
 456         Passes the \c B_NAVIGABLE to the BTextView.
 457
 458         \since Haiku R1
 459 */
 460
 461
 462 /*!
 463         \fn BHandler* BTextControl::ResolveSpecifier(BMessage* message, int32 index,
 464                 BMessage* specifier, int32 what, const char* property)
 465         \copydoc BHandler::ResolveSpecifier()
 466 */
 467
 468
 469 /*!
 470         \fn status_t BTextControl::GetSupportedSuites(BMessage* data)
 471         \copydoc BHandler::GetSupportedSuites()
 472 */
 473
 474
 475 /*!
 476         \fn BSize BTextControl::MinSize()
 477         \brief Returns the text control's minimum size.
 478
 479         \return The text control's minimum size as a BSize.
 480
 481         \since Haiku R1
 482 */
 483
 484
 485 /*!
 486         \fn BSize BTextControl::MaxSize()
 487         \brief Returns the text control's maximum size.
 488
 489         \return The text control's maximum size as a BSize.
 490
 491         \since Haiku R1
 492 */
 493
 494
 495 /*!
 496         \fn BSize BTextControl::PreferredSize()
 497         \brief Returns the text control's preferred size.
 498
 499         \return The text control's preferred size as a BSize.
 500
 501         \since Haiku R1
 502 */
 503
 504
 505 /*!
 506         \fn BAlignment BTextControl::LayoutAlignment()
 507         \brief Returns the alignment used by this control in a layout.
 508
 509         \since Haiku R1
 510 */
 511
 512
 513
 514 /*!
 515         \fn BLayoutItem* BTextControl::CreateLabelLayoutItem()
 516         \brief Creates a label layout item and returns a pointer to it
 517                (Layout constructor only).
 518
 519         \sa CreateTextViewLayoutItem()
 520
 521         \since Haiku R1
 522 */
 523
 524
 525 /*!
 526         \fn BLayoutItem* BTextControl::CreateTextViewLayoutItem()
 527         \brief Creates a text view layout item and returns a pointer to it.
 528
 529         \sa CreateLabelLayoutItem()
 530
 531         \since Haiku R1
 532 */
 533
 534
 535 /*!
 536         \fn void BTextControl::DoLayout()
 537         \brief Layout view within the layout context.
 538
 539         \remark This is only meaningful if the view is part of a BLayout.
 540
 541         \since Haiku R1
 542 */
 543
 544
 545 /*!
 546         status_t BTextControl::SetIcon(const BBitmap* icon, uint32 flags)
 547         \copydoc BControl::SetIcon()
 548 */