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