1/* 2 * Copyright 2011-2015, 2019 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * John Scipione, jscipione@gmail.com 7 * Joseph Groover, looncraz@looncraz.net 8 * 9 * Corresponds to: 10 * headers/os/interface/View.h hrev52835 11 * src/kits/interface/View.cpp hrev53446 12 */ 13 14 15/*! 16 \file View.h 17 \ingroup interface 18 \ingroup libbe 19 \brief BView class definition and support data structures. 20 21 \since BeOS R5 22*/ 23 24 25// mouse buttons 26 27 28/*! 29 \var B_PRIMARY_MOUSE_BUTTON 30 \brief Primary mouse button mask parameter. 31 32 The primary mouse button should be used for main operations (selecting, 33 dragging, or opening objects). 34 35 This maps to B_MOUSE_BUTTON(1). 36 37 \since BeOS R3 38*/ 39 40 41/*! 42 \var B_SECONDARY_MOUSE_BUTTON 43 \brief Secondary mouse button mask parameter. 44 45 The secondary button should be used for additional operations on the 46 pointed objects, such as popup menus. 47 48 This maps to B_MOUSE_BUTTON(2). 49 50 \since BeOS R3 51*/ 52 53 54/*! 55 \var B_TERTIARY_MOUSE_BUTTON 56 \brief Tertiary mouse button mask parameter. 57 58 The tertiary button should be used for clipboard paste. 59 60 This maps to B_MOUSE_BUTTON(3). 61 62 \since BeOS R3 63*/ 64 65 66/*! 67 \var B_MOUSE_BUTTON(n) 68 \brief Compute mouse button mask for button n 69 70 Buttons are numbered from 1 to 32. 71 72 Some mice may not have more than 2 buttons, so the extra buttons should 73 only be used as shortcuts for actions that can be done in alternative ways. 74 75 \since Haiku R1 76*/ 77 78 79// mouse transit 80 81 82/*! 83 \var B_ENTERED_VIEW 84 \brief Mouse transit entered view. 85 86 \since BeOS R3 87*/ 88 89 90/*! 91 \var B_INSIDE_VIEW 92 \brief Mouse transit inside view. 93 94 \since BeOS R3 95*/ 96 97 98/*! 99 \var B_EXITED_VIEW 100 \brief Mouse transit exited view. 101 102 \since BeOS R3 103*/ 104 105 106/*! 107 \var B_OUTSIDE_VIEW 108 \brief Mouse transit outside view. 109 110 \since BeOS R5 111*/ 112 113 114// event mask 115 116 117/*! 118 \var B_POINTER_EVENTS 119 \brief Mouse pointer events mask parameter. 120 121 \since BeOS R5 122*/ 123 124 125/*! 126 \var B_KEYBOARD_EVENTS 127 \brief Keyboard events mask parameter. 128 129 \since BeOS R5 130*/ 131 132 133// event mask options 134 135 136/*! 137 \var B_LOCK_WINDOW_FOCUS 138 \brief Prevents the attached window from losing its focused state while 139 the mouse is held down. 140 141 \since BeOS R5 142*/ 143 144 145/*! 146 \var B_SUSPEND_VIEW_FOCUS 147 \brief Events normally sent to the focus view are suppressed. 148 149 \since BeOS R5 150*/ 151 152 153/*! 154 \var B_NO_POINTER_HISTORY 155 \brief Send only the most recent MouseMoved() event to the view. 156 157 \note New in Haiku: unless this flag is specified, both BWindow and 158 BView::GetMouse() will filter out older mouse moved messages. 159 160 \since BeOS R5 161*/ 162 163 164/*! 165 \var B_FULL_POINTER_HISTORY 166 \brief Send all MouseMoved() events to the view. 167 168 \since Haiku R1 169*/ 170 171 172// event tracking 173 174 175/*! 176 \var B_TRACK_WHOLE_RECT 177 \brief The whole rectangle moves with the cursor. 178 179 \since BeOS R3 180*/ 181 182 183/*! 184 \var B_TRACK_RECT_CORNER 185 \brief The left top corner is fixed while the right and bottom edges 186 move with the cursor. 187 188 \since BeOS R3 189*/ 190 191 192// set font mask 193 194 195/*! 196 \var B_FONT_FAMILY_AND_STYLE 197 \brief Font family and style mask parameter. 198 199 \since BeOS R3 200*/ 201 202 203/*! 204 \var B_FONT_SIZE 205 \brief Font size mask parameter. 206 207 \since BeOS R3 208*/ 209 210 211/*! 212 \var B_FONT_SHEAR 213 \brief Font shear mask parameter. 214 215 \since BeOS R3 216*/ 217 218 219/*! 220 \var B_FONT_ROTATION 221 \brief Font rotation mask parameter. 222 223 \since BeOS R3 224*/ 225 226 227/*! 228 \var B_FONT_SPACING 229 \brief Font spacing mask parameter. 230 231 \since BeOS R3 232*/ 233 234 235/*! 236 \var B_FONT_ENCODING 237 \brief Font encoding mask parameter. 238 239 \since BeOS R3 240*/ 241 242 243/*! 244 \var B_FONT_FACE 245 \brief Font face mask parameter. 246 247 \since BeOS R3 248*/ 249 250 251/*! 252 \var B_FONT_FLAGS 253 \brief Font flags mask parameter. 254 255 \since BeOS R3 256*/ 257 258 259/*! 260 \var B_FONT_FALSE_BOLD_WIDTH 261 \brief Font false bold width mask parameter. 262 263 \since Haiku R1 264*/ 265 266 267/*! 268 \var B_FONT_ALL 269 \brief Font all properties mask parameter. 270 271 \since BeOS R3 272*/ 273 274 275// view flags 276 277 278/*! 279 \var B_FULL_UPDATE_ON_RESIZE 280 \brief Redraw the entire view on resize. 281 282 \since BeOS R3 283*/ 284 285 286/*! 287 \var _B_RESERVED1_ 288 \brief Reserved for future use. 289 290 \since Haiku R1 291*/ 292 293 294/*! 295 \var B_WILL_DRAW 296 \brief Indicates that the view will do its own drawing. 297 298 \since BeOS R3 299*/ 300 301 302/*! 303 \var B_PULSE_NEEDED 304 \brief Indicates that the view accepts Pulse() messages. 305 306 \since BeOS R3 307*/ 308 309 310/*! 311 \var B_NAVIGABLE_JUMP 312 \brief Indicates this is the default keyboard navigation view. 313 314 \since BeOS R3 315*/ 316 317/*! 318 \var B_FRAME_EVENTS 319 \brief View responds to frame move and resize events. 320 321 \since BeOS R3 322*/ 323 324 325/*! 326 \var B_NAVIGABLE 327 \brief The view is able to receive focus for keyboard navigation. 328 Typically focus is indicated by drawing a blue rectangle around the view. 329 330 \since BeOS R3 331*/ 332 333 334/*! 335 \var B_SUBPIXEL_PRECISE 336 \brief The view draws with sub-pixel precision. 337 338 If this flag is not specified, drawing coordinates will be rounded 339 to the nearest integer. 340 341 \since BeOS R5 342*/ 343 344 345/*! 346 \var B_DRAW_ON_CHILDREN 347 \brief Indicates that the view responds to the DrawAfterChildren() hook 348 method. 349 350 \since BeOS R5 351*/ 352 353 354/*! 355 \var B_INPUT_METHOD_AWARE 356 \brief Indicates the view understands input method add-ons, as used 357 for complex text input in CJK and other languages. 358 359 \since BeOS R5 360*/ 361 362 363/*! 364 \var B_SCROLL_VIEW_AWARE 365 \brief Indicates the view will properly manage scrollbars that 366 have been targeted to it, i.e. update their ranges and proportions. 367 368 \since Haiku R1 369*/ 370 371 372/*! 373 \var B_SUPPORTS_LAYOUT 374 \brief The view supports the layout APIs, i.e. it doesn't require an 375 frame rectangle to be specified. 376 377 \since Haiku R1 378*/ 379 380 381/*! 382 \var B_INVALIDATE_AFTER_LAYOUT 383 \brief Indicates that the view should be redraw after being added to 384 a layout. 385 386 \since Haiku R1 387*/ 388 389 390// resize mask variables, internal variables but are in a public header. 391 392 393/*! 394 \var _RESIZE_MASK_ 395 \brief Resize mask. Do not use. 396 397 \since Haiku R1 398*/ 399 400 401/*! 402 \var _VIEW_TOP_ 403 \brief View top mask variable. Do not use. 404 405 \since Haiku R1 406*/ 407 408 409/*! 410 \var _VIEW_LEFT_ 411 \brief View left mask variable. Do not use. 412 413 \since Haiku R1 414*/ 415 416 417/*! 418 \var _VIEW_BOTTOM_ 419 \brief View bottom mask variable. Do not use. 420 421 \since Haiku R1 422*/ 423 424 425/*! 426 \var _VIEW_RIGHT_ 427 \brief View right mask variable. Do not use. 428 429 \since Haiku R1 430*/ 431 432 433/*! 434 \var _VIEW_CENTER_ 435 \brief View center mask variable. Do not use. 436 437 \since Haiku R1 438*/ 439 440 441/*! 442 \fn inline uint32 _rule_(uint32 r1, uint32 r2, uint32 r3, uint32 r4) 443 \brief Internal function, do not use. 444 445 \since Haiku R1 446*/ 447 448 449// resize mask 450 451 452/*! 453 \var B_FOLLOW_NONE 454 \brief Follow none resize mask parameter. Equivalent to 455 \c B_FOLLOW_LEFT | \c B_FOLLOW_TOP. The view maintains its position 456 in its parent's coordinate system but not in the screen coordinate 457 system. 458 459 \since BeOS R3 460*/ 461 462 463/*! 464 \var B_FOLLOW_ALL_SIDES 465 \brief Follow all sides resize mask parameter. Equivalent to 466 \c B_FOLLOW_LEFT_RIGHT | \c B_FOLLOW_TOP_BOTTOM. The view will be resized 467 with its parent view both horizontally and vertically. 468 469 \since BeOS R3 470*/ 471 472 473/*! 474 \var B_FOLLOW_ALL 475 \brief Equivalent to \c B_FOLLOW_ALL_SIDES. 476 477 \since BeOS R3 478*/ 479 480 481// horizontal resize mask 482 483 484/*! 485 \var B_FOLLOW_LEFT 486 \brief The margin between the left side of the view and the left side 487 of its parent remains constant. 488 489 \since BeOS R3 490*/ 491 492 493/*! 494 \var B_FOLLOW_RIGHT 495 \brief The margin between the right side of the view and the right side 496 of its parent remains constant. 497 498 \since BeOS R3 499*/ 500 501 502/*! 503 \var B_FOLLOW_LEFT_RIGHT 504 \brief The margin between the left and right sides of the view and the left 505 and right sides of its parent both remain constant. 506 507 \since BeOS R3 508*/ 509 510 511/*! 512 \var B_FOLLOW_H_CENTER 513 \brief The view maintains a constant relationship to the horizontal center 514 of its parent view. 515 516 \since BeOS R3 517*/ 518 519 520// vertical resize mask 521 522 523/*! 524 \var B_FOLLOW_TOP 525 \brief The margin between the top of the view and the top of its parent 526 remains constant. 527 528 \since BeOS R3 529*/ 530 531 532/*! 533 \var B_FOLLOW_BOTTOM 534 \brief The margin between the bottom of the view and the bottom of its 535 parent remains constant. 536 537 \since BeOS R3 538*/ 539 540 541/*! 542 \var B_FOLLOW_TOP_BOTTOM 543 \brief The margin between the top and bottom sides of the view and the 544 top and bottom sides of its parent both remain constant. 545 546 \since BeOS R3 547*/ 548 549 550/*! 551 \var B_FOLLOW_V_CENTER 552 \brief The view maintains a constant relationship to the vertical center 553 of its parent view. 554 555 \since BeOS R3 556*/ 557 558 559/*! 560 \var B_FOLLOW_LEFT_TOP 561 \brief The margins between the left and top sides of the view and the left 562 and top sides of its parent remain constant. 563 564 \since Haiku R1 565*/ 566 567 568/*! 569 \class BView 570 \ingroup interface 571 \ingroup libbe 572 \brief View base class. 573 574 A BView is a rectangular area within a window that responds to mouse clicks 575 and key presses, and acts as a surface for you to draw on. 576 577 Most Interface Kit classes, with the notable exception of BWindow inherit from 578 BView. Some of the time you might use a BView object as is, but most of the 579 time you subclass BView to do something unique. 580 581 To create a subclass of BView you generally override one or more of BView's 582 hook methods to respond to user events such as MouseDown() or FrameMoved(). 583 By default a BView does nothing in its hook methods unless otherwise stated, 584 it's up to you to define what happens. To override the look of a BView you 585 should override the Draw() or DrawAfterChildren() methods. See the section on 586 Hook Methods below for more details. 587 588 When a BView object is first created it has no parent or child views. How you 589 add a view to the view hierarchy depends on if you want to use a standard 590 view with a defined frame rectangle or to use the Layout APIs to position and 591 size your view instead. 592 593 If you create a standard view you need to add it to a window or another view 594 using the AddChild() method, if you create a layout view you need to add your 595 view to a layout using BLayout::AddView() or by adding it to a layout builder. 596 597 Views are not very interesting until they, or one of their parents, are 598 attached to a window as many of BView's methods depend on a connection to the 599 App Server to do their work. In order to prevent multiple views from altering 600 the window simultaneously though locking is required. To perform an action 601 while the window is locked you issue the following code: 602 603\code 604if (Window()->LockLooper()) { 605 ... 606 Window()->UnlockLooper() 607} 608\endcode 609 610 Whenever App Server calls a hook method it automatically locks the BWindow for 611 you. 612 613 Only one view attached to a window is able to receive keyboard events at a 614 time. The view that is able to receive keyboard events such as KeyDown() is 615 called the "focus view". MakeFocus() gives or removes focus from a view. 616 Call IsFocus() to determine whether or not the view is the window's current 617 focus view. 618 619 When a view has focus an indicator should be drawn to inform the user. Typically 620 the view is surrounded by a blue rectangle to indicate that it is the window's 621 focus view. The color can be queried using the keyboard_navigation_color() 622 function in InterfaceDefs.h 623 624 Each view has its own coordinate system with the origin point (0.0, 0.0) 625 located at the top left corner. You can convert a BPoint or BRect to or from 626 the view's coordinate system to the coordinate system of its parent, or 627 of the screen's coordinate system. See the section on Coordinate Conversion 628 Methods for more details. 629 630 The Application Server clips a BView to the region where it's permitted to 631 draw which is never larger than the view's bound rectangle. A view can never 632 draw outside its bounds nor can it draw outside of the bounds rectangle of any 633 parent view. 634 635 You may limit the clipping region further by passing a BRegion object to 636 ConstrainClippingRegion(). You can obtain the current clipping region by 637 calling GetClippingRegion(). 638 639 Each view has a ViewColor() that fills the frame rectangle before the 640 view does any drawing of its own. The default view color is white, you may 641 change the view color by calling SetViewColor() or, as of Haiku R1, 642 SetViewUIColor(). A commonly used view color is \c B_PANEL_BACKGROUND_COLOR 643 which is a user-defined color used as the view color of most applications. 644 If you set the view color to \c B_TRANSPARENT_COLOR then the Application Server 645 won't erase the clipping region of the view before updating, this should only 646 be used if the view erases itself by drawing on every pixel in the clipping 647 region. 648 649 If you want to set the view color of a view to be the same as its parent you 650 need to set it within the AttachedToWindow() method of the view like so: 651 652\code 653SetViewColor(Parent()->ViewColor()); 654\endcode 655 656 \since BeOS R3 657*/ 658 659 660 661/*! 662 \fn BView::BView(const char* name, uint32 flags, BLayout* layout) 663 \brief Layout constructor. 664 665 To be used as part of a BLayout. You may use the Layout Methods found below 666 to set the size and alignment constraints of the view. 667 668 \c B_SUPPORTS_LAYOUT is automatically set to the view. The view flags can be 669 set after the view has been constructed by calling the SetFlags() methods. 670 671 \param name The name of the view, can be \c NULL. 672 \param flags The view flags, a mask of one or more of the following: 673 - \c B_FULL_UPDATE_ON_RESIZE Redraw the entire view on resize. 674 - \c B_WILL_DRAW Indicates that the view will do its own drawing. 675 - \c B_PULSE_NEEDED The view accepts Pulse() messages. 676 - \c B_NAVIGABLE_JUMP Default for keyboard navigation. 677 - \c B_FRAME_EVENTS Responds to move and resize events. 678 - \c B_NAVIGABLE Able to receive keyboard navigation focus. 679 - \c B_SUBPIXEL_PRECISE Draws with sub-pixel precision. 680 - \c B_DRAW_ON_CHILDREN Responds to DrawAfterChildren(). 681 - \c B_INPUT_METHOD_AWARE Allows access input method add-ons. 682 - \c B_SUPPORTS_LAYOUT Supports the layout APIs, i.e. it doesn't 683 use a frame rectangle. 684 - \c B_INVALIDATE_AFTER_LAYOUT Is redraw after added to a layout. 685 \param layout A \a layout to set the view to. 686 687 \since Haiku R1 688*/ 689 690 691/*! 692 \fn BView::BView(BRect frame, const char* name, uint32 resizingMode, 693 uint32 flags) 694 \brief Standard constructor. 695 696 A newly constructed BView object has no parent, you must assign it one by 697 passing it into the AddChild() method of another view or window. Once the 698 view or a parent view has been attached to a window the view becomes part of 699 that window's view hierarchy. 700 701 When the BView object is added as a child the \a frame values are interpreted 702 in the parent's coordinate system. The frame rectangle should be specified in 703 integral values to align on pixel boundaries, decimal values will be rounded. 704 705 The resizing mode flags and view flags can be set after the view has been 706 constructed by calling the SetResizingMode() and SetFlags() methods. 707 708 \param frame The \a frame rectangle of the view. 709 \param name The name of the view, can be \c NULL. 710 \param resizingMode Defines the view's behavior when its parent is resized. 711 \n\n It combines one of the following horizontal resizing constants: 712 \li \c B_FOLLOW_TOP The margin between the top of the view and the top 713 of its parent remains constant. 714 \li \c B_FOLLOW_BOTTOM The margin between the bottom of the view and 715 the bottom of its parent remains constant. 716 \li \c B_FOLLOW_TOP_BOTTOM The margin between the top and bottom sides 717 of the view and the top and bottom sides of the parent both remain 718 constant. 719 \li \c B_FOLLOW_V_CENTER Maintains a constant relationship to the 720 vertical center of the parent view. 721 722 with one of the following vertical resizing constants: 723 \li \c B_FOLLOW_LEFT The margin between the left side of the view and 724 the left side of its parent remains constant. 725 \li \c B_FOLLOW_RIGHT The margin between the right side of the view and 726 the right side of the parent remains constant. 727 \li \c B_FOLLOW_LEFT_RIGHT The margin between the left and right sides 728 of the view and the left and right sides of its parent both remain 729 constant. 730 \li \c B_FOLLOW_H_CENTER The view maintains a constant relationship to 731 the horizontal center of the parent view. 732 733 or use one of the following combined horizontal/vertical constants: 734 \li \c B_FOLLOW_NONE Equivalent to \c B_FOLLOW_LEFT | \c B_FOLLOW_TOP. 735 \li \c B_FOLLOW_ALL_SIDES Equivalent to 736 \c B_FOLLOW_LEFT_RIGHT | \c B_FOLLOW_TOP_BOTTOM. 737 \param flags The view flags, a mask of one or more of the following: 738 - \c B_FULL_UPDATE_ON_RESIZE Redraw the entire view on resize. 739 - \c B_WILL_DRAW Indicates that the view will do its own drawing. 740 - \c B_PULSE_NEEDED The view accepts Pulse() messages. 741 - \c B_NAVIGABLE_JUMP Default for keyboard navigation. 742 - \c B_FRAME_EVENTS Responds to move and resize events. 743 - \c B_NAVIGABLE Able to receive keyboard navigation focus. 744 - \c B_SUBPIXEL_PRECISE Draws with sub-pixel precision. 745 - \c B_DRAW_ON_CHILDREN Responds to DrawAfterChildren(). 746 - \c B_INPUT_METHOD_AWARE Allows access input method add-ons. 747 - \c B_SUPPORTS_LAYOUT Supports the layout APIs, i.e. it doesn't 748 use a frame rectangle. 749 - \c B_INVALIDATE_AFTER_LAYOUT Is redraw after added to a layout. 750 751 \since BeOS R3 752*/ 753 754 755/*! 756 \fn BView::BView(BMessage* archive) 757 \brief Archive constructor. 758 759 \param archive The message data to construct the view from. 760 761 \since BeOS R3 762*/ 763 764 765/*! 766 \fn BView::~BView() 767 \brief Destructor method. 768 769 Deletes the view and all children freeing any memory used. 770 771 \since BeOS R3 772*/ 773 774 775/*! 776 \name Archiving 777*/ 778 779 780//! @{ 781 782 783/*! 784 \fn BArchivable* BView::Instantiate(BMessage* data) 785 \brief Creates a new BView object from the \a data message. 786 787 \returns A newly created BView object or \c NULL if the message doesn't 788 contain an archived BView. 789 790 \since BeOS R3 791*/ 792 793 794/*! 795 \fn status_t BView::Archive(BMessage* data, bool deep) const 796 \brief Archives the object into the \a data message. 797 798 \param data A pointer to the BMessage object to archive the object into. 799 \param deep Whether or not to archive child views as well. 800 801 \return A status code, \c B_OK if everything went well or an error code 802 otherwise. 803 \retval B_OK The object was archived successfully. 804 \retval B_NO_MEMORY Ran out of memory while archiving the object. 805 806 \since BeOS R3 807*/ 808 809 810//! @} 811 812 813/*! 814 \name Hook Methods 815*/ 816 817 818//! @{ 819 820 821/*! 822 \fn status_t BView::AllUnarchived(const BMessage* from) 823 \brief Hook method called when all views have been unarchived. 824 825 \since BeOS R3 826*/ 827 828 829/*! 830 \fn status_t BView::AllArchived(BMessage* into) const 831 \brief Hook method called when all views have been archived. 832 833 \since BeOS R3 834*/ 835 836 837/*! 838 \fn void BView::AllAttached() 839 \brief Similar to AttachedToWindow() but this method is triggered after 840 all child views have already been attached to a window. 841 842 \since BeOS R3 843*/ 844 845 846/*! 847 \fn void BView::DetachedFromWindow() 848 \brief Hook method called when the object is detached from a window. 849 850 \since BeOS R3 851*/ 852 853 854/*! 855 \fn void BView::AttachedToWindow() 856 \brief Hook method called when the object is attached to a window. 857 858 \since BeOS R3 859*/ 860 861 862/*! 863 \fn void BView::AllDetached() 864 \brief Similar to AttachedToWindow() but this method is triggered after 865 all child views have already been detached from a window. 866 867 \since BeOS R3 868*/ 869 870 871/*! 872 \fn void BView::Draw(BRect updateRect) 873 \brief Draws the area of the view that intersects \a updateRect. 874 875 Derived classes should override this method to draw their view. 876 877 \remark This is an hook method called by the Interface Kit, you don't have to 878 call it yourself. If you need to forcefully redraw the view consider 879 calling Invalidate() instead. 880 881 \param updateRect The rectangular area to be drawn. 882 883 \since BeOS R3 884*/ 885 886 887/*! 888 \fn void BView::DrawAfterChildren(BRect updateRect) 889 \brief Perform any drawing that needs to be done after child view have 890 already been drawn. 891 892 \param updateRect The rectangular area to drawn in. 893 894 \since BeOS R5 895*/ 896 897 898/*! 899 \fn void BView::FrameMoved(BPoint newPosition) 900 \brief Hook method called when the view is moved. 901 902 \param newPosition The point of the top left corner of the frame 903 that the view has been moved to. 904 905 \since BeOS R3 906*/ 907 908 909/*! 910 \fn void BView::FrameResized(float newWidth, float newHeight) 911 \brief Hook method called when the view is resized. 912 913 \param newWidth The new width of the view. 914 \param newHeight The new height of the view. 915 916 \since BeOS R3 917*/ 918 919 920/*! 921 \fn void BView::KeyDown(const char* bytes, int32 numBytes) 922 \brief Hook method called when a keyboard key is pressed. 923 924 \param bytes The bytes of the key combination pressed. 925 \param numBytes The number of bytes in \a bytes. 926 927 \since BeOS R3 928*/ 929 930 931/*! 932 \fn void BView::KeyUp(const char* bytes, int32 numBytes) 933 \brief Hook method called when a keyboard key is released. 934 935 \param bytes The bytes of the key combination pressed. 936 \param numBytes The number of bytes in \a bytes. 937 938 \since BeOS R3 939*/ 940 941 942/*! 943 \fn virtual void BView::LayoutChanged() 944 \brief Hook function that is called when the layout if this view, or one of 945 its children, has changed. 946 947 \since Haiku R1 948*/ 949 950 951/*! 952 \fn void BView::LayoutInvalidated(bool descendants) 953 \brief Hook method called when the layout is invalidated. 954 955 \param descendants Whether or not child views have also been invalidated. 956 957 \since Haiku R1 958*/ 959 960 961/*! 962 \fn void BView::MessageReceived(BMessage* message) 963 \brief Handle \a message received by the associated looper. 964 965 \param message The \a message received by the associated looper. 966 967 \see BHandler::MessageReceived() 968 969 \since BeOS R3 970*/ 971 972 973/*! 974 \fn void BView::MouseDown(BPoint where) 975 \brief Hook method called when a mouse button is pressed. 976 977 \param where The point on the screen where to mouse pointer is when 978 the mouse button is pressed. 979 980 \since BeOS R3 981*/ 982 983 984/*! 985 \fn void BView::MouseUp(BPoint where) 986 \brief Hook method called when a mouse button is released. 987 988 \param where The point on the screen where to mouse pointer is when 989 the mouse button is released. 990 991 \since BeOS R3 992*/ 993 994 995/*! 996 \fn void BView::MouseMoved(BPoint where, uint32 code, 997 const BMessage* dragMessage) 998 \brief Hook method called when the mouse is moved. 999 1000 \param where The new location of the mouse in the view's coordinate system. 1001 \param code One of the following: 1002 - \c B_ENTERED_VIEW The cursor has just entered the view. 1003 - \c B_INSIDE_VIEW The cursor is inside the view. 1004 - \c B_EXITED_VIEW The cursor has left the view's bounds. This only gets sent 1005 if the scope of the mouse events that the view can receive has been 1006 expanded by SetEventMask() or SetMouseEventMask(). 1007 - \c B_OUTSIDE_VIEW The cursor is outside the view. This only gets sent if the 1008 scope of the mouse events that the view can receive has been expanded by 1009 SetEventMask() or SetMouseEventMask(). 1010 \param dragMessage If a drag-and-drop operation is taking place this is a 1011 pointer to a BMessage that holds the drag information, otherwise the 1012 pointer is \c NULL. 1013 1014 \sa SetEventMask(), SetMouseEventMask() 1015 \sa DragMessage() 1016 1017 \since BeOS R3 1018*/ 1019 1020 1021/*! 1022 \fn void BView::Pulse() 1023 \brief Hook method called when the view receives a \c B_PULSE 1024 message. 1025 1026 An action is performed each time the App Server calls the Pulse() method. 1027 The pulse rate is set by SetPulseRate(). You can implement Pulse() to do 1028 anything you want. The default version does nothing. The pulse granularity 1029 is no better than once per 100,000 microseconds. 1030 1031 \sa SetPulseRate() 1032 1033 \since BeOS R3 1034*/ 1035 1036 1037/*! 1038 \fn void BView::TargetedByScrollView(BScrollView* scrollView) 1039 \brief Hook method called when the view becomes the target of 1040 \a scrollView. 1041 1042 \param scrollView The BScrollView object that has targeted the view. 1043 1044 \since Haiku R1 1045*/ 1046 1047 1048/*! 1049 \fn void BView::WindowActivated(bool active) 1050 \brief Hook method called when the attached window is activated or 1051 deactivated. 1052 1053 \param active \c true when the window becomes activated, \c false when the 1054 window becomes deactivated. 1055 1056 \since BeOS R3 1057*/ 1058 1059 1060//! @} 1061 1062 1063/*! 1064 \fn BRect BView::Bounds() const 1065 \brief Returns the view's frame rectangle in the view's coordinate system. 1066 1067 \return The view's bounding rectangle in the view's coordinate system. 1068 1069 \since BeOS R3 1070*/ 1071 1072 1073/*! 1074 \fn BRect BView::Frame() const 1075 \brief Returns the view's frame rectangle in the parent's coordinate system. 1076 1077 \returns The view's frame rectangle in the parent's coordinate system. 1078 1079 \since BeOS R3 1080*/ 1081 1082 1083/*! 1084 \name Coordinate Conversions 1085*/ 1086 1087 1088//! @{ 1089 1090 1091/*! 1092 \fn void BView::ConvertToParent(BPoint* point) const 1093 \brief Convert \a point to the parent's coordinate system in place. 1094 1095 \param point A pointer to a BPoint object to convert. 1096 1097 \since BeOS R3 1098*/ 1099 1100 1101/*! 1102 \fn BPoint BView::ConvertToParent(BPoint point) const 1103 \brief Returns \a point converted to the parent's coordinate system. 1104 1105 \param point A BPoint object to convert. 1106 1107 \return A new BPoint object in the parent's coordinate system. 1108 1109 \since BeOS R3 1110*/ 1111 1112 1113/*! 1114 \fn void BView::ConvertFromParent(BPoint* point) const 1115 \brief Convert \a point from the parent's coordinate system to the 1116 view's coordinate system in place. 1117 1118 \param point A pointer to a BPoint object to convert. 1119 1120 \since BeOS R3 1121*/ 1122 1123 1124/*! 1125 \fn BPoint BView::ConvertFromParent(BPoint point) const 1126 \brief Returns \a point converted from the parent's coordinate system to 1127 the view's coordinate system. 1128 1129 \param point A BPoint object to convert. 1130 1131 \return A new BPoint object in the view's coordinate system. 1132 1133 \since BeOS R3 1134*/ 1135 1136 1137/*! 1138 \fn void BView::ConvertToParent(BRect* rect) const 1139 \brief Convert \a rect to the parent's coordinate system in place. 1140 1141 \param rect A pointer to a BRect object to convert. 1142 1143 \since BeOS R3 1144*/ 1145 1146 1147/*! 1148 \fn BRect BView::ConvertToParent(BRect rect) const 1149 \brief Returns \a rect converted to the parent's coordinate system. 1150 1151 \param rect A BRect object to convert. 1152 1153 \return A new BRect object in the parent's coordinate system. 1154 1155 \since BeOS R3 1156*/ 1157 1158 1159/*! 1160 \fn void BView::ConvertFromParent(BRect* rect) const 1161 \brief Convert \a rect from the parent's coordinate system to the 1162 view's coordinate system in place. 1163 1164 \param rect A pointer to a BRect object to convert. 1165 1166 \since BeOS R3 1167*/ 1168 1169 1170/*! 1171 \fn BRect BView::ConvertFromParent(BRect rect) const 1172 \brief Returns \a rect converted from the parent's coordinate system to the 1173 view's coordinate system. 1174 1175 \param rect A BRect object to convert. 1176 1177 \return A new BRect object in the view's coordinate system. 1178 1179 \since BeOS R3 1180*/ 1181 1182 1183/*! 1184 \fn void BView::ConvertToScreen(BPoint* point) const 1185 \brief Convert \a point to the screen's coordinate system in place. 1186 1187 \param point A pointer to a BPoint object to convert. 1188 1189 \since BeOS R3 1190*/ 1191 1192 1193/*! 1194 \fn BPoint BView::ConvertToScreen(BPoint point) const 1195 \brief Returns \a point converted to the screen's coordinate system. 1196 1197 \param point A BPoint object to convert. 1198 1199 \return A new BPoint object in the screen's coordinate system. 1200 1201 \since BeOS R3 1202*/ 1203 1204 1205/*! 1206 \fn void BView::ConvertFromScreen(BPoint* point) const 1207 \brief Convert \a point from the screen's coordinate system to the 1208 view's coordinate system in place. 1209 1210 \param point A pointer to a BPoint object to convert. 1211 1212 \since BeOS R3 1213*/ 1214 1215 1216/*! 1217 \fn BPoint BView::ConvertFromScreen(BPoint point) const 1218 \brief Returns \a point converted from the screen's coordinate system to 1219 the view's coordinate system. 1220 1221 \param point A BPoint object to convert. 1222 1223 \return A new BPoint object in the view's coordinate system. 1224 1225 \since BeOS R3 1226*/ 1227 1228 1229/*! 1230 \fn void BView::ConvertToScreen(BRect* rect) const 1231 \brief Convert \a rect to the screen's coordinate system in place. 1232 1233 \param rect A pointer to a BRect object to convert. 1234 1235 \since BeOS R3 1236*/ 1237 1238 1239/*! 1240 \fn BRect BView::ConvertToScreen(BRect rect) const 1241 \brief Returns \a rect converted to the screen's coordinate system. 1242 1243 \param rect A BRect object to convert. 1244 1245 \return A new BRect object in the screen's coordinate system. 1246 1247 \since BeOS R3 1248*/ 1249 1250 1251/*! 1252 \fn void BView::ConvertFromScreen(BRect* rect) const 1253 \brief Convert \a rect from the screen's coordinate system to the 1254 view's coordinate system in place. 1255 1256 \param rect A pointer to a BRect object to convert. 1257 1258 \since BeOS R3 1259*/ 1260 1261 1262/*! 1263 \fn BRect BView::ConvertFromScreen(BRect rect) const 1264 \brief Returns \a rect converted from the screen's coordinate system to the 1265 view's coordinate system. 1266 1267 \param rect A BRect object to convert. 1268 1269 \return A new BRect object in the view's coordinate system. 1270 1271 \since BeOS R3 1272*/ 1273 1274 1275/*! 1276 \fn uint32 BView::Flags() const 1277 \brief Return the view flags set in the constructor or by SetFlags(). 1278 1279 \return The view flags as a uint32 mask. 1280 1281 \sa SetFlags() 1282 1283 \since BeOS R3 1284*/ 1285 1286 1287/*! 1288 \fn void BView::SetFlags(uint32 flags) 1289 \brief Sets the view flags to the \a flags mask. 1290 1291 \param flags The view flags to set as a uint32 mask. 1292 1293 \sa Flags() 1294 1295 \since BeOS R3 1296*/ 1297 1298 1299//! @} 1300 1301 1302/*! 1303 \fn void BView::Hide() 1304 \brief Hides the view without removing it from the view hierarchy. 1305 1306 Calls to Hide() and Show() are cumulative. A visible view becomes hidden 1307 once the number of Hide() calls exceeds the number of Show() calls. 1308 1309 \sa Show() 1310 \sa BWindow::Hide() 1311 \sa IsHidden() 1312 1313 \since BeOS R3 1314*/ 1315 1316 1317/*! 1318 \fn void BView::Show() 1319 \brief Shows the view making it visible. 1320 1321 Calls to Hide() and Show() are cumulative. A hidden view becomes visible 1322 again once the number of Show() calls matches the number of Hide() calls. 1323 1324 \sa Hide() 1325 \sa BWindow::Show() 1326 \sa IsHidden() 1327 1328 \since BeOS R3 1329*/ 1330 1331 1332/*! 1333 \fn bool BView::IsFocus() const 1334 \brief Returns whether or not the view is the window's current focus view. 1335 1336 The focus view changes as the user moves from one view to another either 1337 by pushing the tab key or by clicking a new view with the mouse. The change 1338 can be made programmatically via the MakeFocus() method. 1339 1340 \returns \c true if the view is the current focus view, \c false otherwise. 1341 1342 \sa MakeFocus() 1343 \sa BWindow::CurrentFocus() 1344 1345 \since BeOS R3 1346*/ 1347 1348 1349/*! 1350 \fn bool BView::IsHidden(const BView* lookingFrom) const 1351 \brief Returns whether or not the view is hidden from the perspective of 1352 \a lookingFrom. 1353 1354 A view is considered hidden if it, any of its parent views, or the window 1355 it's attached to has had the Hide() method called on it. This method 1356 allows you to determine the hidden status of a view from a different point 1357 on the view hierarchy. 1358 1359 \param lookingFrom The view used as a base when determining the hidden 1360 status of the BView object. 1361 1362 \return \c true if the view was hidden via the Hide() method, \c false 1363 otherwise. 1364 1365 \since Haiku R1 1366*/ 1367 1368 1369/*! 1370 \fn bool BView::IsHidden() const 1371 \brief Returns whether or not the view is hidden. 1372 1373 A view can be hidden either by calling Hide() on the view, calling Hide() 1374 on a parent view or calling Hide() on the window that the view is attached 1375 to. When a BWindow or BView is hidden, all its descendants are also hidden. 1376 1377 This method only returns whether the view or an ancestor view has had the 1378 Hide() method called on it, it doesn't consider if the view is obscured 1379 by another view or is off-screen. A BView is not hidden by default. 1380 1381 \return \c true if the view was hidden via the Hide() method, \c false 1382 otherwise. 1383 1384 \since BeOS R3 1385*/ 1386 1387 1388/*! 1389 \fn bool BView::IsPrinting() const 1390 \brief Returns whether or not the view is drawing to a printer. 1391 1392 This method should only be called from the Draw() or DrawAfterChildren() 1393 methods. If called from any other method this method returns \c false. 1394 1395 The view may choose different fonts, images, or colors when drawing to a 1396 printer vs. when drawing to the screen. 1397 1398 \return Returns \c true if drawing to a printer, \c false otherwise. 1399 1400 \since BeOS R3 1401*/ 1402 1403 1404/*! 1405 \fn BPoint BView::LeftTop() const 1406 \brief Returns the left top corner point. 1407 1408 \return The left top corner of the view as a BPoint object. 1409 1410 \since BeOS R3 1411*/ 1412 1413 1414/*! 1415 \fn void BView::SetResizingMode(uint32 mode) 1416 \brief Sets the resizing mode of the view according to the \a mode mask. 1417 1418 The resizing mode is first set in the BView constructor. 1419 1420 \sa ResizingMode() 1421 1422 \since BeOS R3 1423*/ 1424 1425 1426/*! 1427 \fn uint32 BView::ResizingMode() const 1428 \brief Returns the resizing mode flags mask set in the constructor or by 1429 SetResizingMode(). 1430 1431 \returns the current resizing mode flags as a uint32 mask. 1432 1433 \sa SetResizingMode() 1434 1435 \since BeOS R3 1436*/ 1437 1438 1439/*! 1440 \fn void BView::SetViewCursor(const BCursor* cursor, bool sync) 1441 \brief Assigns \a cursor to the view. 1442 1443 This cursor will be displayed when the mouse is positioned inside the view. 1444 1445 \param cursor The BCursor object to assign to the view. 1446 \param sync If \c true App Server is synchronized immediately forcing the 1447 change to occur. If \c false, the change will be put in the queue and 1448 will take effect when the pending requests are processed. 1449 1450 \since BeOS R5 1451*/ 1452 1453 1454/*! 1455 \fn void BView::Flush() const 1456 \brief Flushes the attached window's connection to App Server. 1457 1458 \note If the view isn't attached to a window, Flush() does nothing. 1459 1460 \since BeOS R3 1461*/ 1462 1463 1464/*! 1465 \fn void BView::Sync() const 1466 \brief Synchronizes the attached window's connection to App Server. 1467 1468 \warning If the view isn't attached to a window, Sync() might crash the 1469 application. 1470 1471 \since BeOS R3 1472*/ 1473 1474 1475/*! 1476 \fn BWindow* BView::Window() const 1477 \brief Returns the window the view is attached to. 1478 1479 \return The window the view is attached to or \c NULL if the view isn't 1480 attached to a window. 1481 1482 \since BeOS R3 1483*/ 1484 1485 1486/*! 1487 \fn void BView::GetPreferredSize(float* _width, float* _height) 1488 \brief Fill out the preferred width and height of the view 1489 into the \a _width and \a _height parameters. 1490 1491 Derived classes should override this method to set the preferred 1492 size of object. 1493 1494 \remark Either the \a _width or \a _height parameter may be set to \c NULL 1495 if you only want to get the other one. 1496 1497 \param[out] _width Pointer to a float to store the width of the view. 1498 \param[out] _height Pointer to a float to store the height of the view. 1499 1500 \since BeOS R3 1501*/ 1502 1503 1504/*! 1505 \fn void BView::ResizeToPreferred() 1506 \brief Resizes the view to its preferred size keeping the position of the 1507 left top corner constant. 1508 1509 \warning It is not recommended to use this method for views that are part 1510 of a BLayout. 1511 1512 \since BeOS R3 1513*/ 1514 1515 1516/*! 1517 \name Input Related 1518*/ 1519 1520 1521//! @{ 1522 1523 1524/*! 1525 \fn void BView::BeginRectTracking(BRect startRect, uint32 style) 1526 \brief Displays an outline rectangle on the view and initiates tracking. 1527 1528 This method is typically called from the MouseDown() while EndRectTracking() 1529 is typically called from the MouseUp method(). 1530 1531 \param startRect The initial frame in the view's coordinate system. 1532 \param style This parameter is set to one of the following: 1533 - \c B_TRACK_WHOLE_RECT The position of the rect changes with the cursor 1534 while its size remains the same. 1535 - \c B_TRACK_RECT_CORNER The left top corner is fixed while the right and 1536 bottom edges move with the cursor. 1537 1538 \since BeOS R3 1539*/ 1540 1541 1542/*! 1543 \fn void BView::EndRectTracking() 1544 \brief Ends tracking removing the outline rectangle from the view. 1545 1546 BeginRectTracking() is typically called from the MouseDown() while this 1547 method is typically called from the MouseUp() method. 1548 1549 \since BeOS R3 1550*/ 1551 1552 1553/*! 1554 \fn void BView::DragMessage(BMessage* message, BRect dragRect, 1555 BHandler* replyTo) 1556 \brief Initiates a drag-and-drop session. 1557 1558 \warning This method only works if the BView objects are attached to a 1559 window. 1560 1561 \param message Contains data to be dragged and dropped on the destination 1562 view. The caller retains responsibility for this object. 1563 \param dragRect An outline rectangle used in place of a bitmap image set in 1564 the view's coordinate system. 1565 \param replyTo The target set to handle the message sent in reply to the 1566 dragged message. If \c NULL the reply is instead directed to the 1567 BView object that initiated the drag-and-drop session. 1568 1569 \since BeOS R3 1570*/ 1571 1572 1573/*! 1574 \fn void BView::DragMessage(BMessage* message, BBitmap* image, 1575 BPoint offset, BHandler* replyTo) 1576 \brief Initiates a drag-and-drop session of an \a image. 1577 1578 \warning This method only works if the BView objects are attached to a 1579 window. 1580 1581 \param message Contains data to be dragged and dropped on the destination 1582 view. The caller retains responsibility for this object. 1583 \param image Bitmap image dragged by the user. The memory used by the bitmap 1584 is freed automatically when the message is dropped. 1585 \param offset The offset to the hotspot within the image in the bitmap's 1586 coordinate system. 1587 \param replyTo The target set to handle the message sent in reply to the 1588 dragged message. If \c NULL the reply is instead directed to the 1589 BView object that initiated the drag-and-drop session. 1590 1591 \since BeOS R3 1592*/ 1593 1594 1595/*! 1596 \fn void BView::DragMessage(BMessage* message, BBitmap* image, 1597 drawing_mode dragMode, BPoint offset, BHandler* replyTo) 1598 \brief Initiates a drag-and-drop session of an \a image with drawing_mode 1599 set by \a dragMode. 1600 1601 \warning This method only works if the BView objects are attached to a 1602 window. 1603 1604 \param message Contains data to be dragged and dropped on the destination 1605 view. The caller retains responsibility for this object. 1606 \param image Bitmap image dragged by the user. The memory used by the bitmap 1607 is freed automatically when the message is dropped. 1608 \param dragMode Sets the drawing_mode used to draw the dragged image. Set to 1609 \c B_OP_ALPHA to drag-and-drop partially transparent images. 1610 \param offset The offset to the hotspot within the image in the bitmap's 1611 coordinate system. 1612 \param replyTo The target set to handle the message sent in reply to the 1613 dragged message. If \c NULL the reply is instead directed to the 1614 BView object that initiated the drag-and-drop session. 1615 1616 \since BeOS R5 1617*/ 1618 1619 1620/*! 1621 \fn void BView::GetMouse(BPoint* _location, uint32* _buttons, 1622 bool checkMessageQueue) 1623 \brief Fills out the cursor location and the current state of the mouse 1624 buttons. 1625 1626 The cursor doesn't have to be located within the view for this method to work, 1627 however, the view must be attached to a window. Don't use this method to track 1628 the mouse in your derived view, implement MouseMoved() instead. 1629 1630 \param[out] _location Filled out with the cursor location in the view's 1631 coordinate system. 1632 \param[out] _buttons Filled out with a mask of the following values: 1633 - \c B_PRIMARY_MOUSE_BUTTON 1634 - \c B_SECONDARY_MOUSE_BUTTON 1635 - \c B_TERTIARY_MOUSE_BUTTON 1636 \param checkMessageQueue If \c true pull from any pending MouseMoved() or 1637 MouseUp() events in the message queue top down before filling out 1638 the current mouse cursor state. 1639 1640 \since BeOS R3 1641*/ 1642 1643 1644/*! 1645 \fn void BView::MakeFocus(bool focus) 1646 \brief Makes the view the current focus view of the window or gives up 1647 being the window's focus view. 1648 1649 The focus view handles selections and KeyDown events when the the attached 1650 window is active. There can be only one focus view at a time per window. 1651 1652 When called with \a focus set to \c true this method first calls 1653 MakeFocus() on the previously focused view with \a focus set to 1654 \c false. 1655 1656 The focus doesn't automatically change when MouseDown() is called so calling 1657 MakeFocus() is the only way to make a view the focus view of a window. 1658 Classes derived from BView that can display the current selection, or that 1659 can accept pasted data should call MakeFocus() in their MouseDown() method 1660 to update the focus view of the window on click. 1661 1662 If the view isn't attached to a window this method has no effect. 1663 1664 \param focus \a true to set focus, \a false to remove it. 1665 1666 \since BeOS R3 1667*/ 1668 1669 1670/*! 1671 \fn BScrollBar* BView::ScrollBar(orientation posture) const 1672 \brief Returns the BScrollBar object that has the BView set as its target. 1673 1674 \param posture Either \c B_VERTICAL to get the vertical scroll bar or 1675 \c B_HORIZONTAL to get the horizontal scroll bar. 1676 1677 \returns the Scrollbar object requested or \c NULL if none found. 1678 1679 \see BScrollBar::SetTarget() 1680 1681 \since BeOS R3 1682*/ 1683 1684 1685/*! 1686 \fn void BView::ScrollBy(float deltaX, float deltaY) 1687 \brief Scroll the view by \a deltaX horizontally and \a deltaY vertically. 1688 1689 \param deltaX The amount to scroll horizontally. 1690 \param deltaY The amount to scroll vertically. 1691 1692 \since BeOS R3 1693*/ 1694 1695 1696/*! 1697 \fn void BView::ScrollTo(float x, float y) 1698 \brief Scroll the view to the point specified by coordinates. 1699 1700 \param x The x-coordinate to scroll the view to. 1701 \param y The y-coordinate to scroll the view to. 1702 1703 \since BeOS R3 1704*/ 1705 1706 1707/*! 1708 \fn virtual void BView::ScrollTo(BPoint where) 1709 \brief Scroll the view to the point specified by \a where. 1710 1711 \param where The location to scroll the view to. 1712 1713 \since BeOS R3 1714*/ 1715 1716 1717/*! 1718 \fn void BView::ScrollWithMouseWheelDelta(BScrollBar* scrollBar, 1719 float delta) 1720 \brief Handle the scroll wheel changing over scrollbars. 1721 1722 - Extract the scrollbar change based on the mouse wheel \a delta into a 1723 protected method of BView. 1724 - The method is called from the MessageReceived() method of BScrollBar. 1725 1726 With this change it is now a bit easier to scroll horizontally around the 1727 system by putting the mouse cursor over a horizontal scrollbar and using 1728 the wheel. 1729 1730 \since Haiku R1 1731*/ 1732 1733 1734/*! 1735 \fn status_t BView::SetEventMask(uint32 mask, uint32 options) 1736 \brief Sets whether or not the view can accept mouse and keyboard 1737 events when not in focus. 1738 1739 If \a mask includes \c B_POINTER_EVENTS then the view will receive mouse 1740 events even when the mouse isn't over the view and if it includes 1741 \c B_KEYBOARD_EVENTS the view will receive keyboard events even if it 1742 isn't in focus. 1743 1744 The \a options mask options are as follows: 1745 - \c B_NO_POINTER_HISTORY Tells App Server to only send the most recent 1746 MouseMoved() event to the view sacrificing some granularity. 1747 - \c B_FULL_POINTER_HISTORY Tells App Server to send all MouseMoved() 1748 events to the view. 1749 1750 \param mask The \a mask of \c B_POINTER_EVENTS and \c B_KEYBOARD_EVENTS 1751 to set. 1752 \param options Sets other event-handling options. 1753 1754 \return \c B_OK if everything went fine or an error code, usually 1755 \c B_ERROR if something went wrong. 1756 1757 \sa EventMask() 1758 1759 \since BeOS R5 1760*/ 1761 1762 1763/*! 1764 \fn uint32 BView::EventMask() 1765 \brief Returns the current event mask. 1766 1767 \return The current event mask as a uint32. 1768 1769 \sa SetEventMask() 1770 1771 \since BeOS R5 1772*/ 1773 1774 1775/*! 1776 \fn status_t BView::SetMouseEventMask(uint32 mask, uint32 options) 1777 \brief Sets whether or not the view can accept mouse and keyboard 1778 events when not in focus from within MouseDown() until the 1779 following MouseUp() event. 1780 1781 The \a options mask options are as follows: 1782 - \c B_NO_POINTER_HISTORY Tells App Server to send only the most recent 1783 MouseMoved() event to the view sacrificing mouse movement granularity. 1784 - \c B_FULL_POINTER_HISTORY Tells App Server to send all MouseMoved() 1785 events to the view. 1786 - \c B_SUSPEND_VIEW_FOCUS Events normally sent to the focus view are 1787 suppressed. While the mouse is held down, the keyboard is ignored. 1788 The view receiving the MouseDown() messages doesn't have to be the 1789 focus view to suppress focused messages. 1790 - \c B_LOCK_WINDOW_FOCUS Prevents the attached window from losing its 1791 focused state while the mouse is held down, even if the mouse leaves 1792 the bounds of the window. 1793 1794 \param mask The \a mask of \c B_POINTER_EVENTS and \c B_KEYBOARD_EVENTS 1795 to set. 1796 \param options Sets other event-handling options. 1797 1798 \return \c B_OK if everything went fine or an error code, usually 1799 \c B_ERROR if something went wrong. 1800 1801 \since BeOS R5 1802*/ 1803 1804 1805//! @} 1806 1807 1808/*! 1809 \name Graphics State 1810*/ 1811 1812 1813//! @{ 1814 1815 1816/*! 1817 \fn void BView::PushState() 1818 \brief Saves the drawing state to the stack. 1819 1820 The drawing state contains the following elements: 1821 - local and global origins 1822 - local and global scales 1823 - local and global clipping regions 1824 - the current drawing mode 1825 - pen size and location 1826 - the font context 1827 - foreground and background color 1828 - line cap and join modes 1829 - miter limit 1830 - stipple pattern 1831 1832 A new state context is created after PushState() is called with a local scale 1833 at 0, a local origin at (0, 0), and no clipping region. 1834 1835 \since BeOS R3 1836*/ 1837 1838 1839/*! 1840 \fn void BView::PopState() 1841 \brief Restores the drawing state from the stack. 1842 1843 \since BeOS R3 1844*/ 1845 1846 1847/*! 1848 \fn void BView::SetOrigin(BPoint where) 1849 \brief Sets the origin in the view's coordinate system. 1850 1851 \param where The point to set the origin to. 1852 1853 \sa Origin() 1854 1855 \since BeOS R3 1856*/ 1857 1858 1859/*! 1860 \fn void BView::SetOrigin(float x, float y) 1861 \brief Sets the origin in the view's coordinate system. 1862 1863 \param x The x-coordinate to set the origin to. 1864 \param y The y-coordinate to set the origin to. 1865 1866 \sa Origin() 1867 1868 \since BeOS R3 1869*/ 1870 1871 1872/*! 1873 \fn BPoint BView::Origin() const 1874 \brief Returns the origin point in the view's coordinate system. 1875 1876 \return The local origin point in the view's coordinate system. 1877 1878 \sa SetOrigin() 1879 1880 \since BeOS R3 1881*/ 1882 1883 1884/*! 1885 \fn void BView::SetTransform(BAffineTransform transform) 1886 \brief Sets a BAffineTransform to transform the coordinate system 1887 1888 \sa See Transform() to get the current transformations, and TranslateBy(), 1889 ScaleBy() and RotateBy() for additional transformation options. 1890 1891 \since Haiku R1 1892*/ 1893 1894 1895/*! 1896 \fn BAffineTransform BView::Transform() const 1897 \brief Returns the current BAffineTransform that is applied to the 1898 coordinate system 1899 1900 \sa SetTransform() 1901 1902 \since Haiku R1 1903*/ 1904 1905 1906/*! 1907 \fn void BView::TranslateBy(double x, double y) 1908 \brief Translate the current view by coordinates. 1909 1910 The translation of \a x and \a y are applied to the current transformation, 1911 not instead of, so it is an additive action. 1912 1913 \sa See Transform() to get the current transformations, SetTransform(), 1914 ScaleBy() and RotateBy() for additional transformation options. 1915 1916 \since Haiku R1 1917*/ 1918 1919 1920/*! 1921 \fn void BView::ScaleBy(double x, double y) 1922 \brief Scale the current view by factors \a x and \a y. 1923 1924 The scaling with factors \a x and \a y are applied to the current 1925 transformation, not instead of, so it is an additive action. 1926 1927 \sa See Transform() to get the current transformations, SetTransform(), 1928 TranslateBy() and RotateBy() for additional transformation options. 1929 1930 \since Haiku R1 1931*/ 1932 1933 1934/*! 1935 \fn void BView::RotateBy(double angleRadians) 1936 \brief Rotate the current view by \a angleRadians. 1937 1938 The rotation is applied to the current transformation, not instead of, so 1939 it is an additive action. 1940 1941 \sa See Transform() to get the current transformations, SetTransform(), 1942 ScaleBy() and TranslateBy() for additional transformation options. 1943 1944 \since Haiku R1 1945*/ 1946 1947 1948/*! 1949 \fn void BView::SetScale(float scale) const 1950 \brief Sets the scale of the coordinate system the view uses for drawing. 1951 1952 The default scale is 1.0. A \a scale value lower than 1.0 reduces the size of 1953 the drawing coordinate system, a \a scale value greater than 1.0 magnifies 1954 the coordinate system; for example, a \a scale value of 0.5 cuts the drawing 1955 drawing area in half moving the drawing closer to the origin while a \a scale 1956 value of 2.0 doubles the drawing area and moving it away from the origin. 1957 1958 Updating the \a scale of view won't update previously drawn elements. 1959 1960 SetScale() calls are not commutative unless you call them across different 1961 drawing states as the following: 1962 1963\code 1964 view->SetScale(2); 1965 view->SetScale(2); 1966 // view's scale is 2 1967 1968 view2->SetScale(2); 1969 view2->PushState(); 1970 view2->SetScale(2); 1971 // view2's scale is 4 1972\endcode 1973 1974 \param scale The scale factor to set. 1975 1976 \since BeOS R3 1977*/ 1978 1979 1980/*! 1981 \fn float BView::Scale() const 1982 \brief Return the current drawing scale. 1983 1984 \return The current drawing scale. 1985 1986 \since BeOS R3 1987*/ 1988 1989 1990/*! 1991 \fn void BView::SetLineMode(cap_mode lineCap, join_mode lineJoin, 1992 float miterLimit) 1993 \brief Set line mode to use PostScript-style line cap and join modes. 1994 1995 \a lineCap determines the shape of the endpoints of stroked paths while 1996 \a lineJoin determines the shape of the corners where two lines meet. 1997 1998 The default miter limit is 10.0 which gives an angle of 11.478341°. 1999 2000 \param lineCap One of the following: 2001 - \c B_ROUND_CAP A semicircle with diameter of line width is drawn at the 2002 endpoint. 2003 - \c B_BUTT_CAP A straight edge is drawn without extending beyond the endpoint. 2004 - \c B_SQUARE_CAP A straight edge is drawn extending past the endpoint by half 2005 the line width. 2006 \param lineJoin One of the following: 2007 - \c B_ROUND_JOIN Same as \c B_ROUND_CAP but for a join. 2008 - \c B_MITER_JOIN The lines are extended until they meet. If angle that they 2009 meet at is greater than the 2*arcsin(1/\a miterLimit) than a bevel join 2010 is used instead. 2011 - \c B_BEVEL_JOIN The area between the caps is filled with a triangle. 2012 - \c B_BUTT_JOIN Same as \c B_BUTT_CAP but for a join. 2013 - \c B_SQUARE_JOIN Same as \c B_SQUARE_CAP but for a join. 2014 \param miterLimit Sets the cut off angle before a miter join becomes a bevel 2015 join calculated by 2*arcsin(1/\a miterLimit). 2016 2017 \since BeOS R3 2018*/ 2019 2020 2021/*! 2022 \fn join_mode BView::LineJoinMode() const 2023 \brief Returns the current line join mode. 2024 2025 \return The current line join mode set to the view. 2026 2027 \since BeOS R3 2028*/ 2029 2030 2031/*! 2032 \fn cap_mode BView::LineCapMode() const 2033 \brief Returns the current line cap mode. 2034 2035 \return The current line cap mode set to the view. 2036 2037 \since BeOS R3 2038*/ 2039 2040 2041/*! 2042 \fn float BView::LineMiterLimit() const 2043 \brief Returns the miter limit used for \c B_MITER_JOIN join mode. 2044 2045 \return The current miter limit set to the view. 2046 2047 \since BeOS R3 2048*/ 2049 2050 2051/*! 2052 \fn void BView::SetFillRule(int32 rule) 2053 \brief Sets the fill rule for the view. 2054 2055 A fill rule is a rule that describes an algorithm that is used to find out 2056 what the inside of a shape is. The concept comes from the SVG format. 2057 2058 See <a href="https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/fill-rule"> 2059 the Mozilla documentation on the fill property of SVG</a> for more 2060 information. 2061 2062 \param rule There are two algorithms: the \c B_NONZERO and the 2063 \c B_EVEN_ODD algorithm. 2064 2065 \since Haiku R1 2066*/ 2067 2068 2069/*! 2070 \fn int32 BView::FillRule() const 2071 \brief Return the current fill mode. 2072 2073 See BView::SetFillRule() for more information. 2074 2075 \returns Returns \c 0 if no fill rule is applied, \c B_EVEN_ODD when the 2076 even-odd algorithm is applied, and \c B_NONZERO if the nonzero 2077 algorithm is applied. 2078 2079 \since Haiku R1 2080*/ 2081 2082 2083/*! 2084 \fn void BView::SetDrawingMode(drawing_mode mode) 2085 \brief Sets the drawing mode of the view. 2086 2087 The default drawing mode is \c B_OP_COPY. 2088 2089 \param mode Set to one of the following: 2090 - \c B_OP_COPY 2091 - \c B_OP_OVER 2092 - \c B_OP_ERASE 2093 - \c B_OP_INVERT 2094 - \c B_OP_SELECT 2095 - \c B_OP_ALPHA 2096 - \c B_OP_MIN 2097 - \c B_OP_MAX 2098 - \c B_OP_ADD 2099 - \c B_OP_SUBTRACT 2100 - \c B_OP_BLEND 2101 2102 \since BeOS R3 2103*/ 2104 2105 2106/*! 2107 \fn drawing_mode BView::DrawingMode() const 2108 \brief Return the current drawing_mode. 2109 2110 \return The current drawing_mode. 2111 2112 \since BeOS R3 2113*/ 2114 2115 2116/*! 2117 \fn void BView::SetBlendingMode(source_alpha srcAlpha, 2118 alpha_function alphaFunc) 2119 \brief Set the blending mode which controls how transparency is used. 2120 2121 \param srcAlpha Set to one of the following: 2122 - \c B_CONSTANT_ALPHA Use the high color's alpha channel. 2123 - \c B_PIXEL_ALPHA Use the alpha value of each pixel when drawing a bitmap. 2124 \param alphaFunc Set to one of the following: 2125 - \c B_ALPHA_OVERLAY Used for drawing a image with transparency over an opaque 2126 background. 2127 - \c B_ALPHA_COMPOSITE_* Used to composite two or more transparent images 2128 together offscreen to produce a new image drawn using 2129 \c B_ALPHA_OVERLAY mode. 2130 \note Modes other than \c B_ALPHA_OVERLAY and \c B_ALPHA_COMPOSITE work 2131 only with \c B_PIXEL_ALPHA. 2132 2133 \since BeOS R5 2134*/ 2135 2136 2137/*! 2138 \fn void BView::GetBlendingMode(source_alpha* srcAlpha, 2139 alpha_function* alphaFunc) const 2140 \brief Fill out \a srcAlpha and \a alphaFunc with the alpha mode and 2141 alpha function of the view. 2142 2143 \param[out] srcAlpha The alpha mode to fill out. 2144 \param[out] alphaFunc The alpha function to fill out. 2145 2146 \since BeOS R5 2147*/ 2148 2149 2150/*! 2151 \fn void BView::MovePenTo(BPoint point) 2152 \brief Move the pen to \a point in the view's coordinate system. 2153 2154 \param point the location to move the pen to. 2155 2156 \since BeOS R3 2157*/ 2158 2159 2160/*! 2161 \fn void BView::MovePenTo(float x, float y) 2162 \brief Move the pen to the point specified by \a x and \a y in the view's 2163 coordinate system. 2164 2165 \param x The horizontal coordinate to move the pen to. 2166 \param y The vertical coordinate to move the pen to. 2167 2168 \since BeOS R3 2169*/ 2170 2171 2172/*! 2173 \fn void BView::MovePenBy(float x, float y) 2174 \brief Move the pen by \a x pixels horizontally and \a y pixels vertically. 2175 2176 \param x The number of pixels to move the pen horizontally. 2177 \param y The number of pixels to move the pen vertically. 2178 2179 \since BeOS R3 2180*/ 2181 2182 2183/*! 2184 \fn BPoint BView::PenLocation() const 2185 \brief Return the current pen location as a BPoint object. 2186 2187 \return The current pen location in the view's coordinate system. 2188 2189 \sa MovePenTo(BPoint) 2190 \sa MovePenTo(float, float) 2191 \sa MovePenBy(float, float) 2192 2193 \since BeOS R3 2194*/ 2195 2196 2197/*! 2198 \fn void BView::SetPenSize(float size) 2199 \brief Set the pen size to \a size. 2200 2201 \param size The pen size to set. 2202 2203 \since BeOS R3 2204*/ 2205 2206 2207/*! 2208 \fn float BView::PenSize() const 2209 \brief Return the current pen size. 2210 2211 \return The current pen size as a float. 2212 2213 \sa SetPenSize() 2214 2215 \since BeOS R3 2216*/ 2217 2218 2219/*! 2220 \fn bool BView::HasDefaultColors() const 2221 \brief Tests if the view has any colors set. 2222 2223 \return Boolean value, true if colors are not set. 2224 2225 \since Haiku R1 2226*/ 2227 2228 2229/*! 2230 \fn bool BView::HasSystemColors() const 2231 \brief Tests if the view is using system "panel" colors. 2232 B_PANEL_BACKGROUND_COLOR for ViewUIColor() 2233 B_PANEL_BACKGROUND_COLOR for LowUIColor() 2234 B_PANEL_TEXT_COLOR for HighUIColor() 2235 2236 \return Boolean value, true if colors are as described. 2237 2238 \since Haiku R1 2239*/ 2240 2241 2242/*! 2243 \fn void BView::AdoptParentColors() 2244 \brief Attempts to use the colors of any parent view. 2245 Will adopt view, low, and high colors. 2246 Should be called in AttachedToWindow() or AllAttached(). 2247 2248 \since Haiku R1 2249*/ 2250 2251 2252/*! 2253 \fn void BView::AdoptSystemColors() 2254 \brief Instructs view to use standard system "panel" colors. 2255 B_PANEL_BACKGROUND_COLOR for ViewUIColor() 2256 B_PANEL_BACKGROUND_COLOR for LowUIColor() 2257 B_PANEL_TEXT_COLOR for HighUIColor() 2258 2259 \since Haiku R1 2260*/ 2261 2262 2263/*! 2264 \fn void BView::AdoptViewColors(BView* view) 2265 \brief Attempts to use the colors of a given view. 2266 Will adopt view, low, and high colors. 2267 2268 \since Haiku R1 2269*/ 2270 2271 2272/*! 2273 \fn void BView::SetHighColor(rgb_color color) 2274 \brief Set the high color of the view. 2275 2276 \param color The color to set. 2277 2278 \since BeOS R3 2279*/ 2280 2281 2282/*! 2283 \fn void BView::SetHighColor(uchar red, uchar green, uchar blue, 2284 uchar alpha) 2285 \brief Set the high color of the view. 2286 2287 \param red The \a red component of the high color. 2288 \param green The \a green component of the high color. 2289 \param blue The \a blue component of the high color. 2290 \param alpha The \a alpha component of the high color. 2291 2292 \since BeOS R3 2293*/ 2294 2295 2296/*! 2297 \fn void BView::SetHighUIColor(color_which which, float tint) 2298 \brief Set the high color of the view to a system constant. 2299 The color will update live with user changes. 2300 2301 \param which The color_which constant to set. 2302 \param tint Optional tint value to use. 2303 2304 \since Haiku R1 2305*/ 2306 2307 2308/*! 2309 \fn rgb_color BView::HighColor() const 2310 \brief Return the current high color. 2311 2312 \return The current high color as an rgb_color struct. 2313 2314 \sa SetHighColor(rgb_color) 2315 \sa SetHighColor(uchar, uchar, uchar, uchar) 2316 2317 \since BeOS R3 2318*/ 2319 2320 2321/*! 2322 \fn color_which BView::HighUIColor(float* tint) const 2323 \brief Return the current high color constant being used. 2324 2325 \param tint Optional float pointer in which to store the tint 2326 value used to modify the system color constant. 2327 \return The current high color constant. 2328 2329 \sa SetHighUIColor(color_which, float) 2330 2331 \since Haiku R1 2332*/ 2333 2334 2335/*! 2336 \fn void BView::SetLowColor(rgb_color color) 2337 \brief Set the low color of the view. 2338 2339 \param color The color to set. 2340 2341 \since BeOS R3 2342*/ 2343 2344 2345/*! 2346 \fn void BView::SetLowColor(uchar red, uchar green, uchar blue, uchar alpha) 2347 \brief Set the low color of the view. 2348 2349 \param red The \a red component of the low color. 2350 \param green The \a green component of the low color. 2351 \param blue The \a blue component of the low color. 2352 \param alpha The \a alpha component of the low color. 2353 2354 \since BeOS R3 2355*/ 2356 2357 2358/*! 2359 \fn void BView::SetLowUIColor(color_which which, float tint) 2360 \brief Set the low color of the view to a system constant. 2361 The color will update live with user changes. 2362 2363 \param which The color_which constant to set. 2364 \param tint Optional tint value to use. 2365 2366 \since Haiku R1 2367*/ 2368 2369 2370/*! 2371 \fn rgb_color BView::LowColor() const 2372 \brief Return the current low color. 2373 2374 \return The current low color as an rgb_color struct. 2375 2376 \sa SetLowColor(rgb_color) 2377 \sa SetLowColor(uchar, uchar, uchar, uchar) 2378 2379 \since BeOS R3 2380*/ 2381 2382 2383/*! 2384 \fn color_which BView::LowUIColor(float* tint) const 2385 \brief Return the current low color constant being used. 2386 2387 \param tint Optional float pointer in which to store the tint 2388 value used to modify the system color constant. 2389 \return The current low color constant. 2390 2391 \sa SetLowUIColor(color_which, float) 2392 2393 \since Haiku R1 2394*/ 2395 2396 2397/*! 2398 \fn void BView::SetViewColor(rgb_color color) 2399 \brief Set the view color of the view. 2400 2401 \param color The color to set. 2402 2403 \since BeOS R3 2404*/ 2405 2406 2407/*! 2408 \fn void BView::SetViewColor(uchar red, uchar green, uchar blue, 2409 uchar alpha) 2410 \brief Set the view color of the view. 2411 2412 \param red The \a red component of the view color. 2413 \param green The \a green component of the view color. 2414 \param blue The \a blue component of the view color. 2415 \param alpha The \a alpha component of the view color. 2416 2417 \since BeOS R3 2418*/ 2419 2420 2421/*! 2422 \fn void BView::SetViewUIColor(color_which which, float tint) 2423 \brief Set the view color of the view to a system constant. 2424 The color will update live with user changes. 2425 2426 \param which The color_which constant to set. 2427 \param tint Optional tint value to use. 2428 2429 \since Haiku R1 2430*/ 2431 2432 2433/*! 2434 \fn rgb_color BView::ViewColor() const 2435 \brief Return the current view color. 2436 2437 \return The current view color as an rgb_color struct. 2438 2439 \sa SetViewColor(rgb_color) 2440 \sa SetViewColor(uchar, uchar, uchar, uchar) 2441 2442 \since BeOS R3 2443*/ 2444 2445 2446/*! 2447 \fn color_which BView::ViewUIColor(float* tint) const 2448 \brief Return the current view color constant being used. 2449 2450 \param tint Optional float pointer in which to store the tint 2451 value used to modify the system color constant. 2452 \return The current view color constant. 2453 2454 \sa SetViewUIColor(color_which, float) 2455 2456 \since Haiku R1 2457*/ 2458 2459 2460/*! 2461 \fn void BView::ForceFontAliasing(bool enable) 2462 \brief Turn anti-aliasing on and off when printing. 2463 2464 Typically want to turn font anti-aliasing off when printing by passing 2465 \c true to this method and then turn it on again by passing in \c false. 2466 2467 This method does not affect characters drawn to the screen. 2468 2469 \param enable If \c true turn off anti-aliasing, if \c false turn on 2470 anti-aliasing. 2471 2472 \since BeOS R5 2473*/ 2474 2475 2476/*! 2477 \fn void BView::SetFont(const BFont* font, uint32 mask) 2478 \brief Set the font of the view. 2479 2480 By passing \c B_FONT_ALL to the \a mask parameter as is the default all 2481 font properties from \a font are set on the view. 2482 2483 \param font A pointer to a const BFont object to set on the view. 2484 \param mask A mask to determine what font properties to set, either pass 2485 in \c B_FONT_ALL to set all font properties or create a mask 2486 containing one or more of the following values to set: 2487 - \c B_FONT_FAMILY_AND_STYLE 2488 - \c B_FONT_SPACING 2489 - \c B_FONT_SIZE 2490 - \c B_FONT_ENCODING 2491 - \c B_FONT_SHEAR 2492 - \c B_FONT_FACE 2493 - \c B_FONT_ROTATION 2494 - \c B_FONT_FLAGS 2495 2496 \see BFont for more details. 2497 2498 \since BeOS R3 2499*/ 2500 2501 2502/*! 2503 \fn void BView::GetFont(BFont* font) const 2504 \brief Fill out \a font with the font set to the view. 2505 2506 \param[out] font The BFont object to fill out. 2507 2508 \since BeOS R3 2509*/ 2510 2511 2512/*! 2513 \fn void BView::GetFontHeight(font_height* height) const 2514 \brief Fill out the font_height struct with the view font. 2515 2516 \param[out] height The font_height struct to fill out. 2517 2518 \since BeOS R3 2519*/ 2520 2521 2522/*! 2523 \fn void BView::SetFontSize(float size) 2524 \brief Set the size of the view's font to \a size. 2525 2526 \param size The font size to set to the view in points. 2527 2528 \since BeOS R3 2529*/ 2530 2531 2532/*! 2533 \fn float BView::StringWidth(const char* string) const 2534 \brief Return the width of \a string set in the font of the view. 2535 2536 \param string The \a string to get the width of. 2537 2538 \return The width of the string in the view's font as a float. 2539 2540 \since BeOS R3 2541*/ 2542 2543 2544/*! 2545 \fn float BView::StringWidth(const char* string, int32 length) const 2546 \brief Return the width of \a string set in the font of the view up to 2547 \a length characters. 2548 2549 \param string The \a string to get the width of. 2550 \param length The maximum number of characters in \a string to consider. 2551 2552 \return The width of the string in the view's font as a float. 2553 2554 \since BeOS R3 2555*/ 2556 2557 2558/*! 2559 \fn void BView::GetStringWidths(char* stringArray[], int32 lengthArray[], 2560 int32 numStrings, float widthArray[]) const 2561 \brief Fill out widths of the strings in \a stringArray set in the font 2562 of the view into \a widthArray. 2563 2564 \param stringArray The array of strings to get the lengths of. 2565 \param lengthArray The number of characters of the strings in \a stringArray 2566 to consider. 2567 \param numStrings The number of strings in \a stringArray. 2568 \param widthArray The array to store the widths of the strings in 2569 \a stringArray. 2570 2571 \since BeOS R3 2572*/ 2573 2574 2575/*! 2576 \fn void BView::TruncateString(BString* string, uint32 mode, float width) const 2577 \brief Truncate \a string with truncation mode \a mode so that it is no wider 2578 than \a width set in the view's font. 2579 2580 When the string is truncated the missing characters are replaced by a 2581 horizontal ellipses. 2582 2583 \param string The string to truncate in place. 2584 \param mode The truncation mode to use, one of the following: 2585 - \c B_TRUNCATE_BEGINNING Truncate from the beginning of the string. 2586 - \c B_TRUNCATE_MIDDLE Truncate from the middle of the string. 2587 - \c B_TRUNCATE_END Truncate from the end of the string. 2588 - \c B_TRUNCATE_SMART Truncate from anywhere based on the string content. 2589 Not currently implemented. 2590 \param width The maximum width to truncate the string to. 2591 2592 \since BeOS R5 2593*/ 2594 2595 2596/*! 2597 \fn void BView::ClipToPicture(BPicture* picture, BPoint where, bool sync) 2598 \brief Intersects the current clipping region of the view with the pixels 2599 of \a picture. 2600 2601 BPicture instances are resolution independent, \a picture is effectively 2602 drawn at the view's resolution and the bitmap produced is used to modify the 2603 clipping region. 2604 2605 The pixels that are at least partially opaque are the ones drawn by 2606 \a picture. 2607 2608 \param picture The BPicture object to intersect with. 2609 \param where Offset in the view's coordinate system. 2610 \param sync If \c false, this method will execute asynchronously. 2611 2612 \since BeOS R5 2613*/ 2614 2615 2616/*! 2617 \fn void BView::ClipToInversePicture(BPicture* picture, BPoint where, 2618 bool sync) 2619 \brief Intersects the current clipping region of the view with the pixels 2620 outside of \a picture. 2621 2622 \param picture The BPicture object to intersect with. 2623 \param where Offset in the view's coordinate system. 2624 \param sync If \c false, this method will execute asynchronously. 2625 2626 \see ClipToPicture() 2627 2628 \since BeOS R5 2629*/ 2630 2631 2632/*! 2633 \fn void BView::ClipToRect(BRect rect) 2634 \brief Intersects the current clipping region of the view with the pixels 2635 of \a rect. 2636 2637 \param rect The BRect that describes the rectangle to intersect with. 2638 2639 \since Haiku R1 2640*/ 2641 2642 2643/*! 2644 \fn void BView::ClipToInverseRect(BRect rect) 2645 \brief Intersects the current clipping region of the view with the pixels 2646 outside of \a rect. 2647 2648 \param rect The BRect that describes the rectangle to intersect with. 2649 2650 \see ClipToRect() 2651 2652 \since Haiku R1 2653*/ 2654 2655 2656/*! 2657 \fn void BView::ClipToShape(BShape* shape) 2658 \brief Intersects the current clipping region of the view with the pixels 2659 of \a shape. 2660 2661 \param shape The BShape that describes the area to intersect with. 2662 2663 \since Haiku R1 2664*/ 2665 2666 2667/*! 2668 \fn void BView::ClipToInverseShape(BShape* shape) 2669 \brief Intersects the current clipping region of the view with the pixels 2670 outside of \a shape. 2671 2672 \param shape The BShape that describes the area to intersect with. 2673 2674 \see ClipToShape() 2675 2676 \since Haiku R1 2677*/ 2678 2679 2680/*! 2681 \fn void BView::GetClippingRegion(BRegion* region) const 2682 \brief Fill out \a region with the view's clipping region. 2683 2684 \param[out] region The BRegion object to fill out. 2685 2686 Get the current clipping region, which is an intersection of the view 2687 visible region on screen (which depends on the view bounds, any child view 2688 hiding parts of it, and overlapping windows) and the constrained clipping 2689 regions set by calls to ConstrainClippingRegion() in the current stack of 2690 drawing states. 2691 2692 \since BeOS R3 2693*/ 2694 2695 2696/*! 2697 \fn void BView::ConstrainClippingRegion(BRegion* region) 2698 \brief Set the clipping region the \a region restricting the area that the 2699 view can draw in. 2700 2701 The Application Server keeps track of the clipping region for each view 2702 attached to a window so that the view can't draw outside of it, 2703 consequently this method works only for views that are attached to a window. 2704 2705 The default clipping region contains the visible area of the view. By 2706 passing a region to this method the clipping area is further restricted. 2707 Passing in \c NULL resets the clipping region back to the default. 2708 2709 Calls to ConstrainClippingRegion() are not cumulative, each time this 2710 method is called it replaces the old clipping region. However, clipping 2711 regions from previous states are intersected to compute the effective 2712 clipping. 2713 2714 Region-based clipping is not affected by the view transform. If you need to 2715 constrain drawing to a transformed region, use ClipToPicture() and 2716 FillRegion() instead. 2717 2718 \param region The region to set the clipping region to or \c NULL 2719 to reset to default. 2720 2721 \since BeOS R3 2722*/ 2723 2724 2725//! @} 2726 2727 2728/*! 2729 \name Drawing Related 2730 2731 The view must be attached to the window for these methods to work unless 2732 otherwise stated. Notes on specific methods are provided below: 2733 2734 DrawBitmap() 2735 DrawTiledBitmap() 2736 2737 DrawBitmap() scales the image to fit if the image has different size than 2738 the destination rectangle. 2739 2740 DrawTiledBitmap() fills the destination rectangle with copies of the source 2741 image, without changing its size. 2742 2743 The asynchronous versions pass the image to Application Server and return 2744 immediately. 2745 2746 This can be more efficient in some cases for example to draw several bitmaps 2747 at once and then call Sync() to tell Application Server to wait for them all 2748 to finish drawing rather than waiting for each one to draw. 2749 2750 DrawPicture() 2751 2752 The asynchronous versions pass the picture to Application Server and return 2753 immediately. 2754 2755 This can be more efficient in some cases for example to draw several pictures 2756 at once and then call Sync() to tell Application Server to wait for them all 2757 to finish drawing rather than waiting for each one to draw. 2758 2759 DrawPicture() doesn't alter the graphics state of the view nor do changes to 2760 the graphics state of the view alter the BPicture object. What the picture 2761 will look like depends on the graphics parameters that were in effect when the 2762 picture was recorded. 2763 2764 DrawString() 2765 2766 The \a string is drawn in the view's current font and is modified by 2767 the other parameters of the font such as its direction (left-to-right or 2768 right-to-left), rotation, spacing, shear, etc. The \a string is always drawn 2769 left to right even if its text direction is set to right-to-left mode. 2770 2771 Drawing a string is fastest in \c B_OP_COPY mode and anti-aliasing can 2772 produce undesirable effects when a string is draw in other modes, especially 2773 if the string is drawn in the same location repeatedly. 2774 2775 DrawString() doesn't erase before drawing. 2776*/ 2777 2778 2779//! @{ 2780 2781 2782/*! 2783 \fn void BView::DrawBitmapAsync(const BBitmap* bitmap, BRect bitmapRect, 2784 BRect viewRect, uint32 options) 2785 \brief Draws \a bitmap on the view within \a viewRect asynchronously. 2786 \a bitmap portion is scaled to fit \a viewRect. 2787 2788 \param bitmap The bitmap to draw onto the view. 2789 \param bitmapRect The portion of the bitmap to draw in the bitmap's 2790 coordinate system. 2791 \param viewRect The area in the view's coordinate system to draw the 2792 bitmap in. 2793 \param options combination of \a bitmap_drawing_options flags 2794 2795 \since Haiku R1 2796*/ 2797 2798 2799/*! 2800 \fn void BView::DrawBitmapAsync(const BBitmap* bitmap, BRect bitmapRect, 2801 BRect viewRect) 2802 \brief Draws \a bitmap on the view within \a viewRect asynchronously. 2803 \a bitmap portion is scaled to fit \a viewRect. 2804 2805 \param bitmap The bitmap to draw onto the view. 2806 \param bitmapRect The portion of the bitmap to draw in the bitmap's 2807 coordinate system. 2808 \param viewRect The area in the view's coordinate system to draw the 2809 bitmap in. 2810 2811 \since BeOS R3 2812*/ 2813 2814 2815/*! 2816 \fn void BView::DrawBitmapAsync(const BBitmap* bitmap, BRect viewRect) 2817 \brief Draws \a bitmap on the view within \a viewRect asynchronously. 2818 \a bitmap is scaled to fit \a viewRect. 2819 2820 \param bitmap The bitmap to draw onto the view. 2821 \param viewRect The area in the view's coordinate system to draw the 2822 bitmap in. 2823 2824 \since BeOS R3 2825*/ 2826 2827 2828/*! 2829 \fn void BView::DrawBitmapAsync(const BBitmap* bitmap, BPoint where) 2830 \brief Draws \a bitmap on the view offset by \a where asynchronously. 2831 2832 \param bitmap The bitmap to draw onto the view. 2833 \param where The location to draw the bitmap in the view's coordinate system. 2834 2835 \since BeOS R3 2836*/ 2837 2838 2839/*! 2840 \fn void BView::DrawBitmapAsync(const BBitmap* bitmap) 2841 \brief Draws \a bitmap on the view asynchronously. 2842 2843 \param bitmap The bitmap to draw onto the view. 2844 2845 \since BeOS R3 2846*/ 2847 2848 2849/*! 2850 \fn void BView::DrawBitmap(const BBitmap* bitmap, BRect bitmapRect, 2851 BRect viewRect, uint32 options) 2852 \brief Draws \a bitmap on the view within \a viewRect. \a bitmap portion 2853 is scaled to fit \a viewRect. 2854 2855 \param bitmap The bitmap to draw onto the view. 2856 \param bitmapRect The portion of the bitmap to draw in the bitmap's 2857 coordinate system. 2858 \param viewRect The area in the view's coordinate system to draw the 2859 bitmap in. 2860 \param options ?? 2861 2862 \since Haiku R1 2863*/ 2864 2865 2866/*! 2867 \fn void BView::DrawBitmap(const BBitmap* bitmap, BRect bitmapRect, 2868 BRect viewRect) 2869 \brief Draws \a bitmap on the view within \a viewRect. \a bitmap portion 2870 is scaled to fit \a viewRect. 2871 2872 \param bitmap The bitmap to draw onto the view. 2873 \param bitmapRect The portion of the bitmap to draw in the bitmap's 2874 coordinate system. 2875 \param viewRect The area in the view's coordinate system to draw the 2876 bitmap in. 2877 2878 \since BeOS R3 2879*/ 2880 2881 2882/*! 2883 \fn void BView::DrawBitmap(const BBitmap* bitmap, BRect viewRect) 2884 \brief Draws \a bitmap on the view within \a viewRect. \a bitmap is scaled 2885 to fit \a viewRect. 2886 2887 \param bitmap The bitmap to draw onto the view. 2888 \param viewRect The area in the view's coordinate system to draw the 2889 bitmap in. 2890 2891 \since BeOS R3 2892*/ 2893 2894 2895/*! 2896 \fn void BView::DrawBitmap(const BBitmap* bitmap, BPoint where) 2897 \brief Draws \a bitmap on the view offset by \a where. 2898 2899 \param bitmap The bitmap to draw onto the view. 2900 \param where The location to draw the bitmap in the view's coordinate system. 2901 2902 \since BeOS R3 2903*/ 2904 2905 2906/*! 2907 \fn void BView::DrawBitmap(const BBitmap* bitmap) 2908 \brief Draws \a bitmap on the view. 2909 2910 \param bitmap The bitmap to draw onto the view. 2911 2912 \since BeOS R3 2913*/ 2914 2915 2916/*! 2917 \fn void BView::DrawTiledBitmapAsync(const BBitmap* bitmap, BRect viewRect, 2918 BPoint phase = B_ORIGIN) 2919 \brief Draws \a bitmap on the view within \a viewRect asynchronously. 2920 If \a bitmap is smaller, it is cloned to fill remaining space 2921 in \a viewRect. 2922 2923 \param bitmap The bitmap to draw onto the view. 2924 \param viewRect The area in the view's coordinate system to draw the 2925 bitmap in. 2926 \param phase Source bitmap offset used as starting point for drawing. 2927 2928 \since Haiku R1 2929*/ 2930 2931 2932/*! 2933 \fn void BView::DrawTiledBitmap(const BBitmap* bitmap, BRect viewRect, 2934 BPoint phase = B_ORIGIN) 2935 \brief Draws \a bitmap on the view within \a viewRect. If \a bitmap is 2936 smaller, it is cloned to fill remaining space in \a viewRect. 2937 2938 \param bitmap The bitmap to draw onto the view. 2939 \param viewRect The area in the view's coordinate system to draw the 2940 bitmap in. 2941 \param phase Source bitmap offset used as starting point for drawing. 2942 2943 \since Haiku R1 2944*/ 2945 2946 2947/*! 2948 \fn void BView::DrawChar(char c) 2949 \brief Draws character \a c onto to the view at the current pen position. 2950 2951 The character is drawn in the view's current font. 2952 2953 \param c The character to draw. 2954 2955 \since BeOS R3 2956*/ 2957 2958 2959/*! 2960 \fn void BView::DrawChar(char c, BPoint location) 2961 \brief Draws character \a c at the specified \a location in the view. 2962 2963 The character is drawn in the view's current font. 2964 2965 \param c The character to draw. 2966 \param location The location in the view to draw the character. 2967 2968 \since BeOS R3 2969*/ 2970 2971 2972/*! 2973 \fn void BView::DrawString(const char* string, escapement_delta* delta) 2974 \brief Draw \a string onto the view at the current pen position. 2975 2976 \param string The string to draw. 2977 \param delta Adds additional width to each character according to the 2978 following fields: 2979 - nonspace(float) The amount of width to add to characters with visible 2980 glyphs. 2981 - space(float) The amount of width to add to characters with escapements 2982 but don't have visible glyphs. 2983 2984 \since BeOS R3 2985*/ 2986 2987 2988/*! 2989 \fn void BView::DrawString(const char* string, BPoint location, 2990 escapement_delta* delta) 2991 \brief Draw \a string onto the view at the specified \a location in the view. 2992 2993 \param string The string to draw. 2994 \param location The location in the view to draw the string. 2995 \param delta Adds additional width to each character according to the 2996 following fields: 2997 - nonspace(float) The amount of width to add to characters with visible 2998 glyphs. 2999 - space(float) The amount of width to add to characters with escapements 3000 but don't have visible glyphs. 3001 3002 \since BeOS R3 3003*/ 3004 3005 3006/*! 3007 \fn void BView::DrawString(const char* string, int32 length, 3008 escapement_delta* delta) 3009 \brief Draw \a string up to \a length characters onto the view at the current 3010 pen position. 3011 3012 \param string The string to draw. 3013 \param length The maximum number of characters in \a string to draw. 3014 \param delta Adds additional width to each character according to the 3015 following fields: 3016 - nonspace(float) The amount of width to add to characters with visible 3017 glyphs. 3018 - space(float) The amount of width to add to characters with escapements 3019 but don't have visible glyphs. 3020 3021 \since BeOS R3 3022*/ 3023 3024 3025/*! 3026 \fn void BView::DrawString(const char* string, int32 length, BPoint location, 3027 escapement_delta* delta) 3028 \brief Draw \a string up to \a length characters onto the view at the 3029 specified \a location in the view. 3030 3031 \param string The string to draw. 3032 \param length The maximum number of characters in \a string to draw. 3033 \param location The location in the view to draw the string. 3034 \param delta Adds additional width to each character according to the 3035 following fields: 3036 - nonspace(float) The amount of width to add to characters with visible 3037 glyphs. 3038 - space(float) The amount of width to add to characters with escapements 3039 but don't have visible glyphs. 3040 3041 \since BeOS R3 3042*/ 3043 3044 3045/*! 3046 \fn void BView::DrawString(const char* string, const BPoint* locations, 3047 int32 locationCount) 3048 \brief Draw \a string \a locationCount times at the specified \a locations. 3049 3050 \param string The string to draw. 3051 \param locations A pointer to an array of BPoint objects to draw the string. 3052 \param locationCount The number of elements in \a locations. 3053 3054 \since Haiku R1 3055*/ 3056 3057 3058/*! 3059 \fn void BView::DrawString(const char* string, int32 length, 3060 const BPoint* locations, int32 locationCount) 3061 \brief Draw \a string up to \a length characters \a locationCount times at the 3062 specified \a locations. 3063 3064 \param string The string to draw. 3065 \param length The maximum number of characters in \a string to draw. 3066 \param locations A pointer to an array of BPoint objects to draw the string. 3067 \param locationCount The number of elements in \a locations. 3068 3069 \since Haiku R1 3070*/ 3071 3072 3073/*! 3074 \fn void BView::StrokeEllipse(BPoint center, float xRadius, float yRadius, 3075 ::pattern pattern) 3076 \brief Stroke the outline of an ellipse starting at \a center with a 3077 horizontal radius of \a xRadius and a vertical radius of \a yRadius. 3078 3079 \param center The center point. 3080 \param xRadius The horizontal radius. 3081 \param yRadius The vertical radius. 3082 \param pattern One of the following: 3083 - \c B_SOLID_HIGH 3084 - \c B_SOLID_LOW 3085 - \c B_MIXED_COLORS 3086 3087 \since BeOS R3 3088*/ 3089 3090 3091/*! 3092 \fn void BView::StrokeEllipse(BRect rect, ::pattern pattern) 3093 \brief Stroke the outline of an ellipse inscribed within \a rect. 3094 3095 \param rect The area within which to inscribe the shape. 3096 \param pattern One of the following: 3097 - \c B_SOLID_HIGH 3098 - \c B_SOLID_LOW 3099 - \c B_MIXED_COLORS 3100 3101 \since BeOS R3 3102*/ 3103 3104 3105/*! 3106 \fn void BView::FillEllipse(BPoint center, float xRadius, float yRadius, 3107 ::pattern pattern) 3108 \brief Fill an ellipse starting at \a center with a horizontal radius 3109 of \a xRadius and a vertical radius of \a yRadius. 3110 3111 \param center The center point. 3112 \param xRadius The horizontal radius. 3113 \param yRadius The vertical radius. 3114 \param pattern One of the following: 3115 - \c B_SOLID_HIGH 3116 - \c B_SOLID_LOW 3117 - \c B_MIXED_COLORS 3118 3119 \since BeOS R3 3120*/ 3121 3122 3123/*! 3124 \fn void BView::FillEllipse(BRect rect, ::pattern pattern) 3125 \brief Fill an ellipse inscribed within \a rect. 3126 3127 \param rect The area within which to inscribe the shape. 3128 \param pattern One of the following: 3129 - \c B_SOLID_HIGH 3130 - \c B_SOLID_LOW 3131 - \c B_MIXED_COLORS 3132 3133 \since BeOS R3 3134*/ 3135 3136 3137/*! 3138 \fn void BView::FillEllipse(BPoint center, float xRadius, float yRadius, 3139 const BGradient& gradient) 3140 \brief Fill an ellipse with the specified \a gradient pattern starting at 3141 \a center with a horizontal radius of \a xRadius and a vertical radius 3142 of \a yRadius. 3143 3144 \param center The center point. 3145 \param xRadius The horizontal radius. 3146 \param yRadius The vertical radius. 3147 \param gradient The gradient pattern to fill the ellipse with. 3148 3149 \since Haiku R1 3150*/ 3151 3152 3153/*! 3154 \fn void BView::FillEllipse(BRect rect, const BGradient& gradient) 3155 \brief Fill an ellipse with the specified \a gradient pattern inscribed within 3156 \a rect. 3157 3158 \param rect The area within which to inscribe the shape. 3159 \param gradient The gradient pattern to fill the ellipse with. 3160 3161 \since Haiku R1 3162*/ 3163 3164 3165/*! 3166 \fn void BView::StrokeArc(BPoint center, float xRadius, float yRadius, 3167 float startAngle, float arcAngle, ::pattern pattern) 3168 \brief Stroke the outline of an arc starting at \a center with a 3169 horizontal radius of \a xRadius and a vertical radius of \a yRadius 3170 starting at \a startAngle and drawing \a arcAngle degrees. 3171 3172 \param center The center point. 3173 \param xRadius The horizontal radius. 3174 \param yRadius The vertical radius. 3175 \param startAngle The angle to begin drawing at. 3176 \param arcAngle The number of degrees of the arc to draw. 3177 \param pattern One of the following: 3178 - \c B_SOLID_HIGH 3179 - \c B_SOLID_LOW 3180 - \c B_MIXED_COLORS 3181 3182 \since BeOS R3 3183*/ 3184 3185 3186/*! 3187 \fn void BView::StrokeArc(BRect rect, float startAngle, float arcAngle, 3188 ::pattern pattern) 3189 \brief Stroke the outline of an arc inscribed within \a rect starting at 3190 \a startAngle and drawing \a arcAngle degrees. 3191 3192 \param rect The area within which to inscribe the shape. 3193 \param startAngle The angle to begin drawing at. 3194 \param arcAngle The number of degrees of the arc to draw. 3195 \param pattern One of the following: 3196 - \c B_SOLID_HIGH 3197 - \c B_SOLID_LOW 3198 - \c B_MIXED_COLORS 3199 3200 \since BeOS R3 3201*/ 3202 3203 3204/*! 3205 \fn void BView::FillArc(BPoint center, float xRadius, float yRadius, 3206 float startAngle, float arcAngle, ::pattern pattern) 3207 \brief Fill an arc starting at \a center with a horizontal radius of 3208 \a xRadius and a vertical radius of \a yRadius starting at 3209 \a startAngle and drawing \a arcAngle degrees. 3210 3211 \param center The center point. 3212 \param xRadius The horizontal radius. 3213 \param yRadius The vertical radius. 3214 \param startAngle The angle to begin drawing at. 3215 \param arcAngle The number of degrees of the arc to draw. 3216 \param pattern One of the following: 3217 - \c B_SOLID_HIGH 3218 - \c B_SOLID_LOW 3219 - \c B_MIXED_COLORS 3220 3221 \since BeOS R3 3222*/ 3223 3224 3225/*! 3226 \fn void BView::FillArc(BPoint center, float xRadius, float yRadius, 3227 float startAngle, float arcAngle, const BGradient& gradient) 3228 \brief Fill an arc with the specified \a gradient pattern starting at 3229 \a center with a horizontal radius of \a xRadius and a vertical 3230 radius of \a yRadius starting at \a startAngle and drawing 3231 \a arcAngle degrees. 3232 3233 \param center The center point. 3234 \param xRadius The horizontal radius. 3235 \param yRadius The vertical radius. 3236 \param startAngle The angle to begin drawing at. 3237 \param arcAngle The number of degrees of the arc to draw. 3238 \param gradient The gradient pattern to fill the arc with. 3239 3240 \since Haiku R1 3241*/ 3242 3243 3244/*! 3245 \fn void BView::FillArc(BRect rect, float startAngle, float arcAngle, 3246 ::pattern pattern) 3247 \brief Fill an arc inscribed within \a rect starting at startAngle and 3248 drawing \a arcAngle degrees. 3249 3250 \param rect The area within which to inscribe the shape. 3251 \param startAngle The angle to begin drawing at. 3252 \param arcAngle The number of degrees of the arc to draw. 3253 \param pattern One of the following: 3254 - \c B_SOLID_HIGH 3255 - \c B_SOLID_LOW 3256 - \c B_MIXED_COLORS 3257 3258 \since BeOS R3 3259*/ 3260 3261 3262/*! 3263 \fn void BView::FillArc(BRect rect, float startAngle, float arcAngle, 3264 const BGradient& gradient) 3265 \brief Fill an arc with the specified \a gradient pattern inscribed within 3266 \a rect starting at startAngle and drawing \a arcAngle degrees. 3267 3268 \param rect The area within which to inscribe the shape. 3269 \param startAngle The angle to begin drawing at. 3270 \param arcAngle The number of degrees of the arc to draw. 3271 \param gradient The gradient pattern to fill the arc with. 3272 3273 \since Haiku R1 3274*/ 3275 3276 3277/*! 3278 \fn void BView::StrokeBezier(BPoint* controlPoints, ::pattern pattern) 3279 \brief Stroke a bezier curve. 3280 3281 \param controlPoints The list of points that form the bezier curve. 3282 \param pattern One of the following: 3283 - \c B_SOLID_HIGH 3284 - \c B_SOLID_LOW 3285 - \c B_MIXED_COLORS 3286 3287 \since BeOS R3 3288*/ 3289 3290 3291/*! 3292 \fn void BView::FillBezier(BPoint* controlPoints, ::pattern pattern) 3293 \brief Fill a bezier curve. 3294 3295 \param controlPoints The list of points that form the bezier curve. 3296 \param pattern One of the following: 3297 - \c B_SOLID_HIGH 3298 - \c B_SOLID_LOW 3299 - \c B_MIXED_COLORS 3300 3301 \since BeOS R3 3302*/ 3303 3304 3305/*! 3306 \fn void BView::FillBezier(BPoint* controlPoints, const BGradient& gradient) 3307 3308 \brief Fill a bezier curve. 3309 3310 \param controlPoints The list of points that form the bezier curve. 3311 \param gradient The gradient pattern to fill the bezier curve with. 3312 3313 \since Haiku R1 3314*/ 3315 3316 3317/*! 3318 \fn void BView::StrokePolygon(const BPolygon* polygon, bool closed, 3319 ::pattern pattern) 3320 \brief Stroke a polygon shape. 3321 3322 \param polygon The polygon shape to stroke. 3323 \param closed Whether or not the last line of the polygon should intersect 3324 with the initial point. 3325 \param pattern One of the following: 3326 - \c B_SOLID_HIGH 3327 - \c B_SOLID_LOW 3328 - \c B_MIXED_COLORS 3329 3330 \since BeOS R3 3331*/ 3332 3333 3334/*! 3335 \fn void BView::StrokePolygon(const BPoint* pointArray, int32 numPoints, 3336 bool closed, ::pattern pattern) 3337 \brief Stroke a polygon shape made up of points specified by \a pointArray. 3338 3339 \param pointArray An array of points that specify the vertices of the 3340 polygon. 3341 \param numPoints The number of points in \a pointArray. 3342 \param closed Whether or not the last line of the polygon should intersect 3343 with the initial point. 3344 \param pattern One of the following: 3345 - \c B_SOLID_HIGH 3346 - \c B_SOLID_LOW 3347 - \c B_MIXED_COLORS 3348 3349 \since BeOS R3 3350*/ 3351 3352 3353/*! 3354 \fn void BView::StrokePolygon(const BPoint* pointArray, int32 numPoints, 3355 BRect bounds, bool closed, ::pattern pattern) 3356 \brief Stroke a polygon shape made up of points specified by \a pointArray 3357 inscribed by \a bounds. 3358 3359 \param pointArray An array of points that specify the vertices of the 3360 polygon. 3361 \param numPoints The number of points in \a pointArray. 3362 \param bounds The smallest rectangle that encloses the points in 3363 \a pointArray. 3364 \param closed Whether or not the last line of the polygon should intersect 3365 with the initial point. 3366 \param pattern One of the following: 3367 - \c B_SOLID_HIGH 3368 - \c B_SOLID_LOW 3369 - \c B_MIXED_COLORS 3370 3371 \since BeOS R3 3372*/ 3373 3374 3375/*! 3376 \fn void BView::FillPolygon(const BPolygon* polygon, ::pattern pattern) 3377 \brief Fill a polygon shape. 3378 3379 \param polygon The polygon shape to fill. 3380 \param pattern One of the following: 3381 - \c B_SOLID_HIGH 3382 - \c B_SOLID_LOW 3383 - \c B_MIXED_COLORS 3384 3385 \since BeOS R3 3386*/ 3387 3388 3389/*! 3390 \fn void BView::FillPolygon(const BPolygon* polygon, 3391 const BGradient& gradient) 3392 \brief Fill a polygon shape with the specified \a gradient pattern. 3393 3394 \param polygon The polygon shape to fill. 3395 \param gradient The gradient pattern to fill the polygon with. 3396 3397 \since Haiku R1 3398*/ 3399 3400 3401/*! 3402 \fn void BView::FillPolygon(const BPoint* pointArray, int32 numPoints, 3403 ::pattern pattern) 3404 \brief Fill a polygon shape made up of points specified by \a pointArray. 3405 3406 \param pointArray An array of points that specify the vertices of the polygon. 3407 \param numPoints The number of points in \a pointArray. 3408 \param pattern One of the following: 3409 - \c B_SOLID_HIGH 3410 - \c B_SOLID_LOW 3411 - \c B_MIXED_COLORS 3412 3413 \since BeOS R3 3414*/ 3415 3416 3417/*! 3418 \fn void BView::FillPolygon(const BPoint* pointArray, int32 numPoints, 3419 const BGradient& gradient) 3420 \brief Fill a polygon shape made up of points specified by \a pointArray 3421 with the specified \a gradient pattern. 3422 3423 \param pointArray An array of points that specify the vertices of the 3424 polygon. 3425 \param numPoints The number of points in \a pointArray. 3426 \param gradient The gradient pattern to fill the polygon with. 3427 3428 \since Haiku R1 3429*/ 3430 3431 3432/*! 3433 \fn void BView::FillPolygon(const BPoint* pointArray, int32 numPoints, 3434 BRect bounds, ::pattern pattern) 3435 \brief Fill a polygon shape made up of points specified by \a pointArray 3436 inscribed by \a bounds. 3437 3438 \param pointArray An array of points that specify the vertices of the 3439 polygon. 3440 \param numPoints The number of points in \a pointArray. 3441 \param bounds The smallest rectangle that encloses the points in 3442 \a pointArray. 3443 \param pattern One of the following: 3444 - \c B_SOLID_HIGH 3445 - \c B_SOLID_LOW 3446 - \c B_MIXED_COLORS 3447 3448 \since BeOS R3 3449*/ 3450 3451 3452/*! 3453 \fn void BView::FillPolygon(const BPoint* pointArray, int32 numPoints, 3454 BRect bounds, const BGradient& gradient) 3455 \brief Fill a polygon shape made up of points specified by \a pointArray 3456 inscribed by \a bounds with the specified \a gradient pattern. 3457 3458 \param pointArray An array of points that specify the vertices of the 3459 polygon. 3460 \param numPoints The number of points in \a pointArray. 3461 \param bounds The smallest rectangle that encloses the points in 3462 \a pointArray. 3463 \param gradient The gradient pattern to fill the polygon with. 3464 3465 \since Haiku R1 3466*/ 3467 3468 3469/*! 3470 \fn void BView::StrokeRect(BRect rect, ::pattern pattern) 3471 \brief Stroke the rectangle specified by \a rect. 3472 3473 \param rect The rectangular area to stroke. 3474 \param pattern One of the following: 3475 - \c B_SOLID_HIGH 3476 - \c B_SOLID_LOW 3477 - \c B_MIXED_COLORS 3478 3479 \since BeOS R3 3480*/ 3481 3482 3483/*! 3484 \fn void BView::FillRect(BRect rect, ::pattern pattern) 3485 \brief Fill the rectangle specified by \a rect. 3486 3487 \param rect The rectangular area to fill. 3488 \param pattern One of the following: 3489 - \c B_SOLID_HIGH 3490 - \c B_SOLID_LOW 3491 - \c B_MIXED_COLORS 3492 3493 \since BeOS R3 3494*/ 3495 3496 3497/*! 3498 \fn void BView::FillRect(BRect rect, const BGradient& gradient) 3499 \brief Fill the rectangle specified by \a rect with the specified 3500 \a gradient pattern. 3501 3502 \param rect The rectangular area to fill. 3503 \param gradient The gradient pattern to fill the rectangle with. 3504 3505 \since Haiku R1 3506*/ 3507 3508 3509/*! 3510 \fn void BView::StrokeRoundRect(BRect rect, float xRadius, float yRadius, 3511 ::pattern pattern) 3512 \brief Stroke the rounded rectangle with horizontal radius \a xRadius and 3513 vertical radius \a yRadius. 3514 3515 \param rect The rectangular area to stroke the round rect within. 3516 \param xRadius The horizontal radius. 3517 \param yRadius The vertical radius. 3518 \param pattern One of the following: 3519 - \c B_SOLID_HIGH 3520 - \c B_SOLID_LOW 3521 - \c B_MIXED_COLORS 3522 3523 \since BeOS R3 3524*/ 3525 3526 3527/*! 3528 \fn void BView::FillRoundRect(BRect rect, float xRadius, float yRadius, 3529 ::pattern pattern) 3530 \brief Fill the rounded rectangle with horizontal radius \a xRadius and 3531 vertical radius \a yRadius. 3532 3533 \param rect The rectangular area to fill the round rect within. 3534 \param xRadius The horizontal radius. 3535 \param yRadius The vertical radius. 3536 \param pattern One of the following: 3537 - \c B_SOLID_HIGH 3538 - \c B_SOLID_LOW 3539 - \c B_MIXED_COLORS 3540 3541 \since BeOS R3 3542*/ 3543 3544 3545/*! 3546 \fn void BView::FillRoundRect(BRect rect, float xRadius, float yRadius, 3547 const BGradient& gradient) 3548 \brief Fill the rounded rectangle with horizontal radius \a xRadius and 3549 vertical radius \a yRadius with the specified \a gradient pattern. 3550 3551 \param rect The rectangular area to fill the round rect within. 3552 \param xRadius The horizontal radius. 3553 \param yRadius The vertical radius. 3554 \param gradient The gradient pattern to fill the round rect with. 3555 3556 \since Haiku R1 3557*/ 3558 3559 3560/*! 3561 \fn void BView::FillRegion(BRegion* region, ::pattern pattern) 3562 \brief Fill \a region. 3563 3564 \param region The \a region to fill. 3565 \param pattern One of the following: 3566 - \c B_SOLID_HIGH 3567 - \c B_SOLID_LOW 3568 - \c B_MIXED_COLORS 3569 3570 \since BeOS R3 3571*/ 3572 3573 3574/*! 3575 \fn void BView::FillRegion(BRegion* region, const BGradient& gradient) 3576 \brief Fill \a region with the specified \a gradient pattern. 3577 3578 \param region The \a region to fill. 3579 \param gradient The gradient pattern to fill the \a region with. 3580 3581 \since Haiku R1 3582*/ 3583 3584 3585/*! 3586 \fn void BView::StrokeTriangle(BPoint point1, BPoint point2, BPoint point3, 3587 BRect bounds, ::pattern pattern) 3588 \brief Stroke the triangle specified by points \a point1, \a point2, and 3589 \a point3 and enclosed by \a bounds. 3590 3591 \param point1 The first point of the triangle. 3592 \param point2 The second point of the triangle. 3593 \param point3 The third point of the triangle. 3594 \param bounds The rectangular area that encloses the triangle. 3595 \param pattern One of the following: 3596 - \c B_SOLID_HIGH 3597 - \c B_SOLID_LOW 3598 - \c B_MIXED_COLORS 3599 3600 \since BeOS R3 3601*/ 3602 3603 3604/*! 3605 \fn void BView::StrokeTriangle(BPoint point1, BPoint point2, BPoint point3, 3606 ::pattern pattern) 3607 \brief Stroke the triangle specified by points \a point1, \a point2, 3608 and \a point3. 3609 3610 \param point1 The first point of the triangle. 3611 \param point2 The second point of the triangle. 3612 \param point3 The third point of the triangle. 3613 \param pattern One of the following: 3614 - \c B_SOLID_HIGH 3615 - \c B_SOLID_LOW 3616 - \c B_MIXED_COLORS 3617 3618 \since BeOS R3 3619*/ 3620 3621 3622/*! 3623 \fn void BView::FillTriangle(BPoint point1, BPoint point2, BPoint point3, 3624 ::pattern pattern) 3625 \brief Fill the triangle specified by points \a point1, \a point2, 3626 and \a point3. 3627 3628 \param point1 The first point of the triangle. 3629 \param point2 The second point of the triangle. 3630 \param point3 The third point of the triangle. 3631 \param pattern One of the following: 3632 - \c B_SOLID_HIGH 3633 - \c B_SOLID_LOW 3634 - \c B_MIXED_COLORS 3635 3636 \since BeOS R3 3637*/ 3638 3639 3640/*! 3641 \fn void BView::FillTriangle(BPoint point1, BPoint point2, BPoint point3, 3642 const BGradient& gradient) 3643 \brief Fill the triangle specified by points \a point1, \a point2, 3644 and \a point3 with the specified \a gradient pattern. 3645 3646 \param point1 The first point of the triangle. 3647 \param point2 The second point of the triangle. 3648 \param point3 The third point of the triangle. 3649 \param gradient The gradient pattern to fill the triangle with. 3650 3651 \since Haiku R1 3652*/ 3653 3654 3655/*! 3656 \fn void BView::FillTriangle(BPoint point1, BPoint point2, BPoint point3, 3657 BRect bounds, ::pattern pattern) 3658 \brief Fill the triangle specified by points \a point1, \a point2, 3659 and \a point3 and enclosed by \a bounds. 3660 3661 \param point1 The first point of the triangle. 3662 \param point2 The second point of the triangle. 3663 \param point3 The third point of the triangle. 3664 \param bounds The rectangular area that encloses the triangle. 3665 \param pattern One of the following: 3666 - \c B_SOLID_HIGH 3667 - \c B_SOLID_LOW 3668 - \c B_MIXED_COLORS 3669 3670 \since BeOS R3 3671*/ 3672 3673 3674/*! 3675 \fn void BView::FillTriangle(BPoint point1, BPoint point2, BPoint point3, 3676 BRect bounds, const BGradient& gradient) 3677 \brief Fill the triangle specified by points \a point1, \a point2, 3678 and \a point3 and enclosed by \a bounds with the specified 3679 \a gradient pattern. 3680 3681 \param point1 The first point of the triangle. 3682 \param point2 The second point of the triangle. 3683 \param point3 The third point of the triangle. 3684 \param bounds The rectangular area that encloses the triangle. 3685 \param gradient The gradient pattern to fill the triangle with. 3686 3687 \since Haiku R1 3688*/ 3689 3690 3691/*! 3692 \fn void BView::StrokeLine(BPoint toPoint, ::pattern pattern) 3693 \brief Stroke a line from the current pen location to the point \a toPoint. 3694 3695 \param toPoint The end point of the line. 3696 \param pattern One of the following: 3697 - \c B_SOLID_HIGH 3698 - \c B_SOLID_LOW 3699 - \c B_MIXED_COLORS 3700 3701 \since BeOS R3 3702*/ 3703 3704 3705/*! 3706 \fn void BView::StrokeLine(BPoint start, BPoint end, ::pattern pattern) 3707 \brief Stroke a line from point \a start to point \a end. 3708 3709 \param start The start point of the line. 3710 \param end The end point of the line. 3711 \param pattern One of the following: 3712 - \c B_SOLID_HIGH 3713 - \c B_SOLID_LOW 3714 - \c B_MIXED_COLORS 3715 3716 \since BeOS R3 3717*/ 3718 3719 3720/*! 3721 \fn void BView::StrokeShape(BShape* shape, ::pattern pattern) 3722 \brief Stroke \a shape. 3723 3724 \param shape The \a shape to stroke. 3725 \param pattern One of the following: 3726 - \c B_SOLID_HIGH 3727 - \c B_SOLID_LOW 3728 - \c B_MIXED_COLORS 3729 3730 \since BeOS R5 3731*/ 3732 3733 3734/*! 3735 \fn void BView::FillShape(BShape* shape, ::pattern pattern) 3736 \brief Fill \a shape. 3737 3738 \param shape The \a shape to fill. 3739 \param pattern One of the following: 3740 - \c B_SOLID_HIGH 3741 - \c B_SOLID_LOW 3742 - \c B_MIXED_COLORS 3743 3744 \since BeOS R5 3745*/ 3746 3747 3748/*! 3749 \fn void BView::FillShape(BShape* shape, const BGradient& gradient) 3750 \brief Fill \a shape with the specified \a gradient pattern. 3751 3752 \param shape The \a shape to fill. 3753 \param gradient The gradient pattern to fill the \a shape with. 3754 3755 \since Haiku R1 3756*/ 3757 3758 3759/*! 3760 \fn void BView::BeginLineArray(int32 count) 3761 \brief Begin a line array of up to \a count lines. 3762 3763 This is a more efficient way of drawing a large number of lines than calling 3764 StrokeLine() repeatedly. First call BeginLineArray() to begin drawing lines, 3765 then call AddLine() for each line you wish to draw, and finally call 3766 EndLineArray() to finish the line array and draw the lines. 3767 3768 These methods don't move the current pen location or change the high or low 3769 colors of the view. \a count should be close to the number of lines you wish 3770 to draw and should be below 256 to draw efficiently. 3771 3772 \param count The maximum number of lines in the line array to draw. 3773 3774 \see StrokeLine() 3775 3776 \since BeOS R3 3777*/ 3778 3779 3780/*! 3781 \fn void BView::AddLine(BPoint start, BPoint end, rgb_color color); 3782 \brief Add a line to the line array drawn from \a start to \a end. 3783 3784 \param start The \a start point of the line. 3785 \param end The \a end point of the line. 3786 \param color The \a color to draw the line. 3787 3788 \since BeOS R3 3789*/ 3790 3791 3792/*! 3793 \fn void BView::EndLineArray() 3794 \brief End the line array drawing the lines. 3795 3796 \since BeOS R3 3797*/ 3798 3799 3800/*! 3801 \fn void BView::SetDiskMode(char* filename, long offset) 3802 \brief Unimplemented. 3803 3804 \since Haiku R1 3805*/ 3806 3807 3808/*! 3809 \fn void BView::BeginPicture(BPicture* picture) 3810 \brief Begins sending drawing instructions to \a picture. 3811 3812 The \a BPicture object is cleared and any successive drawing instructions sent 3813 to the view are redirected to \a picture until EndPicture() is called. To 3814 append drawing instructions to a BPicture object without clearing it first 3815 call AppendToPicture() instead. 3816 3817 The view doesn't display anything to the screen while it's recording to \a 3818 picture. Use the DrawPicture() method to render the \a picture. 3819 3820 Only drawing instructions performed directly on the view, not its child views 3821 are send to the BPicture object and BPicture captures only primitive graphics 3822 operations. The view must be attached to a window for the drawing instruction 3823 to be recorded. Drawing instructions are recorded even if the view is hidden or 3824 resides outside the clipping region or the window is off-screen. 3825 3826 \param picture The BPicture object to record drawing instructions to. 3827 3828 \since BeOS R3 3829*/ 3830 3831 3832/*! 3833 \fn void BView::AppendToPicture(BPicture* picture) 3834 \brief Appends drawing instructions to \a picture without clearing it first. 3835 3836 \param picture The BPicture object to record drawing instructions to. 3837 3838 \since BeOS R3 3839*/ 3840 3841 3842/*! 3843 \fn BPicture* BView::EndPicture() 3844 \brief Ends the drawing instruction recording session and returns the 3845 BPicture object passed to BeginPicture() or AppendToPicture(). 3846 3847 \return The BPicture object passed to BeginPicture() or AppendToPicture(). 3848 3849 \since BeOS R3 3850*/ 3851 3852 3853/*! 3854 \fn void BView::SetViewBitmap(const BBitmap* bitmap, BRect srcRect, 3855 BRect dstRect, uint32 followFlags, uint32 options) 3856 \brief Sets the background \a bitmap of the view. 3857 3858 All drawing to the view occurs over \a bitmap. Any visible regions not 3859 covered by \a bitmap are filled with the current background color. 3860 3861 Once \a bitmap has been passed in and this method returns the caller may 3862 safely delete the object. 3863 3864 \param bitmap The background bitmap to set to the view. 3865 \param srcRect Specifies the area of \a bitmap to use. 3866 \param dstRect Specifies the area of the view to set \a bitmap to. 3867 \param followFlags Specifies the as the view is resized. See the BView 3868 constructor for more details. 3869 \param options Specifies additional view options. The only option currently 3870 available is \c B_TILE_BITMAP which tiles the bitmap across the view. 3871 3872 \since BeOS R4 3873*/ 3874 3875 3876/*! 3877 \fn void BView::SetViewBitmap(const BBitmap* bitmap, uint32 followFlags, 3878 uint32 options) 3879 \brief Sets the background \a bitmap of the view. 3880 3881 All drawing to the view occurs over \a bitmap. Any visible regions not 3882 covered by \a bitmap are filled with the current background color. 3883 3884 Once \a bitmap has been passed in and this method returns the caller may 3885 safely delete the object. 3886 3887 \param bitmap The background bitmap to set to the view. 3888 \param followFlags Specifies the as the view is resized. See the BView 3889 constructor for more details. 3890 \param options Specifies additional view options. The only option currently 3891 available is \c B_TILE_BITMAP which tiles the bitmap across the view. 3892 3893 \since BeOS R4 3894*/ 3895 3896 3897/*! 3898 \fn void BView::ClearViewBitmap() 3899 \brief Clears the background bitmap of the view if it has one. 3900 3901 \since BeOS R4 3902*/ 3903 3904 3905/*! 3906 \fn status_t BView::SetViewOverlay(const BBitmap* overlay, BRect srcRect, 3907 BRect dstRect, rgb_color* colorKey, uint32 followFlags, uint32 options) 3908 \brief Sets the \a overlay bitmap of the view. 3909 3910 \a colorKey specifies which color pixels in \a overlay are treated as transparent 3911 allowing the pixels of the view to show through. 3912 3913 Once \a overlay has been passed in and this method returns the caller may 3914 safely delete the object. 3915 3916 \param overlay The overlay bitmap to set to the view. 3917 \param srcRect Specifies the area of \a overlay to use. 3918 \param dstRect Specifies the area of the view to set \a overlay to. 3919 \param colorKey The color in \a overlay to treat as transparent. 3920 \param followFlags Specifies the as the view is resized. See the BView 3921 constructor for more details. 3922 \param options Specifies additional view options. The only option currently 3923 available is \c B_TILE_BITMAP which tiles the bitmap across the view. 3924 3925 \since BeOS R5 3926*/ 3927 3928 3929/*! 3930 \fn status_t BView::SetViewOverlay(const BBitmap* overlay, 3931 rgb_color* colorKey, uint32 followFlags, uint32 options) 3932 \brief Sets the \a overlay bitmap of the view. 3933 3934 \a colorKey specifies which color pixels in \a overlay are treated as transparent 3935 allowing the pixels of the view to show through. 3936 3937 Once \a overlay has been passed in and this method returns the caller may 3938 safely delete the object. 3939 3940 \param overlay The overlay bitmap to set to the view. 3941 \param colorKey The color in \a overlay to treat as transparent. 3942 \param followFlags Specifies the as the view is resized. See the BView 3943 constructor for more details. 3944 \param options Specifies additional view options. The only option currently 3945 available is \c B_TILE_BITMAP which tiles the bitmap across the view. 3946 3947 \since BeOS R5 3948*/ 3949 3950 3951/*! 3952 \fn void BView::ClearViewOverlay() 3953 \brief Clears the overlay bitmap of the view if it has one. 3954 3955 \since BeOS R5 3956*/ 3957 3958 3959/*! 3960 \fn void BView::CopyBits(BRect src, BRect dst) 3961 \brief Copy the bits from the \a src rectangle to the \a dst rectangle in the 3962 view's coordinate system. 3963 3964 If the rectangles are of different sizes than \a src is scaled to fit. \a src 3965 is clipped if a part of \a dst lies outside of the visible region of the view. 3966 Only the visible portions of \a src are copied. 3967 3968 The view must be attached to a window for this method to work. 3969 3970 \param src The source rectangle to copy bits from. 3971 \param dst The destination rectangle to copy bits to. 3972 3973 \since BeOS R3 3974*/ 3975 3976 3977/*! 3978 \fn void BView::DrawPicture(const BPicture* picture) 3979 \brief Draws the \a picture at the view's current pen position. 3980 3981 \param picture The BPicture object to draw. 3982 3983 \since BeOS R3 3984*/ 3985 3986 3987/*! 3988 \fn void BView::DrawPicture(const BPicture* picture, BPoint where) 3989 \brief Draws the \a picture at the location in the view specified by \a where. 3990 3991 \param picture The BPicture object to draw. 3992 \param where The point on the view to draw \a picture. 3993 3994 \since BeOS R3 3995*/ 3996 3997 3998/*! 3999 \fn void BView::DrawPicture(const char* filename, long offset, BPoint where) 4000 \brief Draws the \a picture from the file specified by \a filename offset by 4001 \a offset bytes at the location in the view specified by \a where. 4002 4003 \param filename The filename of the file containing the picture to draw. 4004 \param where The point on the view to draw the picture. 4005 \param offset The number of bytes to offset in the file to find the picture. 4006 4007 \since BeOS R4 4008*/ 4009 4010 4011/*! 4012 \fn void BView::DrawPictureAsync(const BPicture* picture) 4013 \brief Draws the \a picture at the view's current pen position. 4014 4015 \param picture The BPicture object to draw. 4016 4017 \since BeOS R5 4018*/ 4019 4020 4021/*! 4022 \fn void BView::DrawPictureAsync(const BPicture* picture, BPoint where) 4023 \brief Draws the \a picture at the location in the view specified by 4024 \a where. 4025 4026 \param picture The BPicture object to draw. 4027 \param where The point on the view to draw \a picture. 4028 4029 \since BeOS R5 4030*/ 4031 4032 4033/*! 4034 \fn void BView::DrawPictureAsync(const char* filename, long offset, 4035 BPoint where) 4036 \brief Draws the \a picture from the file specified by \a filename offset 4037 by \a offset bytes at the location in the view specified by 4038 \a where. 4039 4040 \param filename The filename of the file containing the picture to draw. 4041 \param where The point on the view to draw the picture. 4042 \param offset The number of bytes to offset in the file to find the 4043 picture. 4044 4045 \since BeOS R5 4046*/ 4047 4048 4049/*! 4050 \fn void BView::BeginLayer(uint8 opacity) 4051 \brief Begins a drawing layer. 4052 4053 This feature of BView allows you to create a separate layer, draw on it, 4054 and blend it in with the rest of the view with a given \a opacity. 4055 Internally, the method creates a new drawing buffer, that you can draw on 4056 using the methods of BView. After finishing your layer, you call EndLayer() 4057 to apply the \a opacity to the layer, and blend it in with the existing 4058 drawing. 4059 4060 You can nest layers, meaning you can call this method while drawing a 4061 layer, to create a sublayer. The layers are mixed and blended in order. 4062 4063 This work was done to support drawing for WebKit. 4064 4065 \sa EndLayer() 4066 4067 \since Haiku R1 4068*/ 4069 4070 4071/*! 4072 \fn void BView::EndLayer() 4073 \brief Finish a layer and blend it in with the view. 4074 4075 This is the counterpart to BeginLayer(). You can nest multiple layer. If 4076 this method is called and the current layer is nested in another layer, the 4077 current layer is applied to the layer above. If this is the only layer, it 4078 will directly blend in to the main view. 4079 4080 \sa BeginLayer() 4081 4082 \since Haiku R` 4083*/ 4084 4085 4086/*! 4087 \fn void BView::Invalidate(BRect invalRect) 4088 \brief Sends a message to App Server to redraw the portion of the view 4089 specified by \a invalRect. 4090 4091 \param invalRect The rectangular area of the view to redraw. 4092 4093 \since BeOS R3 4094*/ 4095 4096 4097/*! 4098 \fn void BView::Invalidate(const BRegion* region) 4099 \brief Sends a message to App Server to redraw the portion of the view 4100 specified by \a region. 4101 4102 \param region The region of the view to redraw. 4103 4104 \since Haiku R1 4105*/ 4106 4107 4108/*! 4109 \fn void BView::Invalidate() 4110 \brief Sends a message to App Server to redraw the view. 4111 4112 \since BeOS R3 4113*/ 4114 4115 4116/*! 4117 \fn void BView::DelayedInvalidate(bigtime_t delay) 4118 \brief Sends a message to App Server to redraw the entire view after 4119 a certain, minimum, delay. Repeated calls to this method may be 4120 merged, but the view is guaranteed to be redrawn after the delay 4121 given in the first call of this method. 4122 4123 \param delay The time, in microseconds, to wait until redrawing the view. 4124 4125 \since Haiku R1 4126*/ 4127 4128 4129/*! 4130 \fn void BView::DelayedInvalidate(bigtime_t delay, BRect invalRect) 4131 \brief Sends a message to App Server to redraw the portion of the view 4132 specified by \a invalRect after a certain, minimum, delay. 4133 Repeated calls to this method may be merged, but the invalidated 4134 rect is guaranteed to be redrawn after the minimum delay given 4135 by the first call of this method. 4136 4137 \param delay The time, in microseconds, to wait until redrawing the view. 4138 \param invalRect The rectangular area of the view to redraw. 4139 4140 \since Haiku R1 4141*/ 4142 4143 4144/*! 4145 \fn void BView::InvertRect(BRect rect) 4146 \brief Inverts the colors within \a rect. 4147 4148 This method is often used to draw a highlighted selection in a view. 4149 4150 \param rect The rectangular area in the view to invert the colors of. 4151 4152 \since BeOS R3 4153*/ 4154 4155 4156//! @} 4157 4158 4159/*! 4160 \name View Hierarchy 4161*/ 4162 4163 4164//! @{ 4165 4166 4167/*! 4168 \fn void BView::AddChild(BView* child, BView* before) 4169 \brief Adds \a child to the view hierarchy immediately before \a before. 4170 4171 A view may only have one parent at a time so \a child must not have already 4172 been added to the view hierarchy. If \a before is \c NULL then \a child is added 4173 to the end of the tree. If the view is attached to a window \a child and all 4174 of its descendent views also become attached to the window invoking an 4175 AttachedToWindow() method on each view. 4176 4177 \param child The child view to add. 4178 \param before The sibling view to add \a child before. 4179 4180 \since BeOS R3 4181*/ 4182 4183 4184/*! 4185 \fn bool BView::AddChild(BLayoutItem* child) 4186 \brief Add the \a child layout item to the view hierarchy. 4187 4188 \param child The child layout item to add. 4189 \return Whether or not \a child was added to the view layout hierarchy. 4190 4191 \since Haiku R1 4192*/ 4193 4194 4195/*! 4196 \fn bool BView::RemoveChild(BView* child) 4197 \brief Removes \a child from the view hierarchy. 4198 4199 \param child The child view to remove. 4200 \return Whether or not \a child was removed from the view hierarchy. 4201 4202 \since BeOS R3 4203*/ 4204 4205 4206/*! 4207 \fn int32 BView::CountChildren() const 4208 \brief Returns the number of child views that this view has. 4209 4210 \return The number of child views. 4211 4212 \since BeOS R3 4213*/ 4214 4215 4216/*! 4217 \fn BView* BView::ChildAt(int32 index) const 4218 \brief Returns a pointer to the child view found at \a index. 4219 4220 \param index The index of the child view to return a pointer of. 4221 4222 \return A pointer to the child view at \a index or \c NULL if not found. 4223 4224 \since BeOS R3 4225*/ 4226 4227 4228/*! 4229 \fn BView* BView::NextSibling() const 4230 \brief Returns a pointer to the next sibling view. 4231 4232 \return A pointer to the next sibling view or \a NULL if not found. 4233 4234 \since BeOS R3 4235*/ 4236 4237 4238/*! 4239 \fn BView* BView::PreviousSibling() const 4240 \brief Returns a pointer to the previous sibling view. 4241 4242 \return A pointer to the previous sibling view or \a NULL if not found. 4243 4244 \since BeOS R3 4245*/ 4246 4247 4248/*! 4249 \fn bool BView::RemoveSelf() 4250 \brief Removes the view and all child views from the view hierarchy. 4251 4252 \returns Whether or not the view was removed from the view hierarchy. 4253 4254 \since BeOS R3 4255*/ 4256 4257 4258/*! 4259 \fn BView* BView::Parent() const 4260 \brief Returns a pointer to the view's parent. 4261 4262 \return A pointer to the parent view or \c NULL if not attached. 4263 4264 \since BeOS R3 4265*/ 4266 4267 4268/*! 4269 \fn BView* BView::FindView(const char* name) const 4270 \brief Returns the view in the view hierarchy with the specified \a name. 4271 4272 \return The view in the view hierarchy with the specified \a name or \c NULL 4273 if not found. 4274 4275 \since BeOS R3 4276*/ 4277 4278 4279//! @} 4280 4281 4282/*! 4283 \name View Frame Alteration 4284 4285 As a view's frame rectangle must be aligned to pixel values all parameters are 4286 rounded to the nearest integer. If the view isn't attached these methods alter the 4287 frame rectangle without triggering FrameMoved(), FrameResized() or Invalidate(). 4288*/ 4289 4290 4291//! @{ 4292 4293 4294/*! 4295 \fn void BView::MoveBy(float deltaX, float deltaY) 4296 \brief Moves the view \a deltaX pixels horizontally and \a deltaY pixels 4297 vertically in the parent view's coordinate system. 4298 4299 \param deltaX The number of pixels to move the view horizontally. 4300 \param deltaY The number of pixels to move the view vertically. 4301 4302 \since BeOS R3 4303*/ 4304 4305 4306/*! 4307 \fn void BView::MoveTo(BPoint where) 4308 \brief Move the view to the location specified by \a where in the parent 4309 view's coordinate system. 4310 4311 \param where The location to move the view to. 4312 4313 \since BeOS R3 4314*/ 4315 4316 4317/*! 4318 \fn void BView::MoveTo(float x, float y) 4319 \brief Move the view to the coordinates specified by \a x in the horizontal 4320 dimension and \a y in the vertical dimension in the parent view's 4321 coordinate system. 4322 4323 \param x The horizontal coordinate to move the view to. 4324 \param y The vertical coordinate to move the view to. 4325 4326 \since BeOS R3 4327*/ 4328 4329 4330/*! 4331 \fn void BView::ResizeBy(float deltaWidth, float deltaHeight) 4332 \brief Resize the view by \a deltaWidth horizontally and \a deltaHeight 4333 vertically without moving the top left corner of the view. 4334 4335 \param deltaWidth The number of pixels to resize the view by horizontally. 4336 \param deltaHeight The number of pixels to resize the view by vertically. 4337 4338 \since BeOS R3 4339*/ 4340 4341 4342/*! 4343 \fn void BView::ResizeTo(float width, float height) 4344 \brief Resize the view to the specified \a width and \a height. 4345 4346 \param width The width to resize the view to. 4347 \param height The height to resize the view to. 4348 4349 \since BeOS R3 4350*/ 4351 4352 4353/*! 4354 \fn void BView::ResizeTo(BSize size) 4355 \brief Resize the view to the dimension specified by \a size. 4356 4357 \param size The \a size to resize the view to. 4358 4359 \since Haiku R1 4360*/ 4361 4362 4363//! @} 4364 4365 4366/*! 4367 \fn status_t BView::GetSupportedSuites(BMessage* data) 4368 \copydoc BHandler::GetSupportedSuites() 4369*/ 4370 4371 4372/*! 4373 \fn BHandler* BView::ResolveSpecifier(BMessage* message, int32 index, 4374 BMessage* specifier, int32 what, const char* property) 4375 \copydoc BHandler::ResolveSpecifier() 4376*/ 4377 4378 4379/*! 4380 \fn status_t BView::Perform(perform_code code, void* _data) 4381 \brief Perform some action. (Internal Method) 4382 4383 This method is available to allow classes to be extended while maintaining 4384 binary compatibility. 4385 4386 The following perform codes are recognized: 4387 - \c PERFORM_CODE_MIN_SIZE: 4388 - \c PERFORM_CODE_MAX_SIZE: 4389 - \c PERFORM_CODE_PREFERRED_SIZE: 4390 - \c PERFORM_CODE_LAYOUT_ALIGNMENT: 4391 - \c PERFORM_CODE_HAS_HEIGHT_FOR_WIDTH: 4392 - \c PERFORM_CODE_GET_HEIGHT_FOR_WIDTH: 4393 - \c PERFORM_CODE_SET_LAYOUT: 4394 - \c PERFORM_CODE_INVALIDATE_LAYOUT: 4395 - \c PERFORM_CODE_DO_LAYOUT: 4396 - \c PERFORM_CODE_GET_TOOL_TIP_AT: 4397 - \c PERFORM_CODE_ALL_UNARCHIVED: 4398 - \c PERFORM_CODE_ALL_ARCHIVED: 4399 4400 \param code The perform code. 4401 \param _data A pointer to store some data. 4402 4403 \returns A status code. 4404 4405 \since Haiku R1 4406*/ 4407 4408 4409/*! 4410 \name Layouting 4411 4412 \note These methods were not available in BeOS R5. 4413*/ 4414 4415 4416//! @{ 4417 4418 4419/*! 4420 \fn BSize BView::MinSize() 4421 \brief Return the minimum size of the view. 4422 4423 \remark This is only meaningful if the view is part of a BLayout. 4424 4425 \return The minimum size of the view as a BSize. 4426 4427 \sa BAbstractLayout::MinSize() 4428 4429 \since Haiku R1 4430*/ 4431 4432 4433/*! 4434 \fn BSize BView::MaxSize() 4435 \brief Return the maximum size of the view. 4436 4437 \remark This is only meaningful if the view is part of a BLayout. 4438 4439 \return The maximum size of the view as a BSize. 4440 4441 \sa BAbstractLayout::MaxSize() 4442 4443 \since Haiku R1 4444*/ 4445 4446 4447/*! 4448 \fn BSize BView::PreferredSize() 4449 \brief Return the preferred size of the view. 4450 4451 \remark This is only meaningful if the view is part of a BLayout. 4452 4453 \return The preferred size of the view as a BSize. 4454 4455 \sa BAbstractLayout::PreferredSize() 4456 4457 \since Haiku R1 4458*/ 4459 4460 4461/*! 4462 \fn virtual BAlignment BView::LayoutAlignment() 4463 \brief Return the current BAlignemnt of the view. 4464 4465 \remark This is only meaningful if the view is part of a BLayout. 4466 4467 \since Haiku R1 4468*/ 4469 4470 4471/*! 4472 \fn void BView::SetExplicitMinSize(BSize size) 4473 \brief Set this view's min size, to be used by MinSize(). 4474 4475 \remark This is only meaningful if the view is part of a BLayout. 4476 4477 \sa BAbstractLayout::SetExplicitMinSize() 4478 4479 \since Haiku R1 4480*/ 4481 4482 4483/*! 4484 \fn void BView::SetExplicitMaxSize(BSize size) 4485 \brief Set this view's max size, to be used by MaxSize(). 4486 4487 \remark This is only meaningful if the view is part of a BLayout. 4488 4489 \sa BAbstractLayout::SetExplicitMaxSize() 4490 4491 \since Haiku R1 4492*/ 4493 4494 4495/*! 4496 \fn void BView::SetExplicitPreferredSize(BSize size) 4497 \brief Set this view's preferred size, to be used by PreferredSize(). 4498 4499 \remark This is only meaningful if the view is part of a BLayout. 4500 4501 \sa BAbstractLayout::SetExplicitPreferredSize() 4502 4503 \since Haiku R1 4504*/ 4505 4506 4507/*! 4508 \fn void BView::SetExplicitSize(BSize size) 4509 \brief Set this view's size. 4510 4511 \remark This is only meaningful if the view is part of a BLayout. 4512 4513 This is a convenience function that calls both SetExplicitMinSize() 4514 and SetExplicitMaxSize() with the \a size parameter. 4515 4516 \since Haiku R1 4517*/ 4518 4519 4520/*! 4521 \fn void BView::SetExplicitAlignment(BAlignment alignment) 4522 \brief Set this view's alignment, to be used by Alignment(). 4523 4524 \remark This is only meaningful if the view is part of a BLayout. 4525 4526 \sa BAbstractLayout::SetExplicitAlignment() 4527 4528 \since Haiku R1 4529*/ 4530 4531 4532/*! 4533 \fn BSize BView::ExplicitMinSize() const 4534 \brief Returns the explicit minimum size. 4535 4536 \remark This is only meaningful if the view is part of a BLayout. 4537 4538 This returns the value that was set by SetExplicitMinSize(). 4539 4540 \since Haiku R1 4541*/ 4542 4543 4544/*! 4545 \fn BSize BView::ExplicitMaxSize() const 4546 \brief Returns the explicit maximum size. 4547 4548 \remark This is only meaningful if the view is part of a BLayout. 4549 4550 This returns the value that was set by SetExplicitMaxSize(). 4551 4552 \since Haiku R1 4553*/ 4554 4555 4556/*! 4557 \fn BSize BView::ExplicitPreferredSize() const 4558 \brief Returns the explicit preferred size. 4559 4560 \remark This is only meaningful if the view is part of a BLayout. 4561 4562 This returns the value that was set by SetExplicitPreferredSize(). 4563 4564 \since Haiku R1 4565*/ 4566 4567 4568/*! 4569 \fn BSize BView::ExplicitAlignment() const 4570 \brief Returns the explicit alignment size. 4571 4572 \remark This is only meaningful if the view is part of a BLayout. 4573 4574 This returns the value that was set by SetExplicitAlignment(). 4575 4576 \since Haiku R1 4577*/ 4578 4579 4580/*! 4581 \fn bool BView::HasHeightForWidth() 4582 \brief Returns whether the layout of the view can calculate a height for a 4583 given width. 4584 4585 \remark This is only meaningful if the view is part of a BLayout. 4586 4587 Use GetHeightForWidth() to actually get the preferred size. 4588 4589 \returns \c true if the height values can be calculated, \c false if they 4590 cannot. 4591 4592 \since Haiku R1 4593*/ 4594 4595 4596/*! 4597 \fn virtual void BView::GetHeightForWidth(float width, float* min, 4598 float* max, float* preferred) 4599 \brief Returns the min, max and preferred height for a given width. 4600 4601 \remark This is only meaningful if the view is part of a BLayout. 4602 4603 \param[in] width The width you want the height to be calculated for. 4604 \param[out] min The minimum height that the layout will request. 4605 \param[out] max The maximum height that the layout will request. 4606 \param[out] preferred The preferred height for this \a width. 4607 4608 \since Haiku R1 4609*/ 4610 4611 4612/*! 4613 \fn void BView::SetLayout(BLayout* layout) 4614 \brief Sets the \a layout of the view. 4615 4616 \param layout The \a layout to set. 4617 4618 \since Haiku R1 4619*/ 4620 4621 4622/*! 4623 \fn BLayout* BView::GetLayout() const 4624 \brief Get the layout of the view. 4625 4626 \remark This is only meaningful if the view is part of a BLayout. 4627 4628 \returns The layout of the view. 4629 4630 \since Haiku R1 4631*/ 4632 4633 4634/*! 4635 \fn void BView::InvalidateLayout(bool descendants) 4636 \brief Invalidate layout. 4637 4638 \remark This is only meaningful if the view is part of a BLayout. 4639 4640 \param descendants Also invalidate its children views. 4641 4642 \since Haiku R1 4643*/ 4644 4645 4646/*! 4647 \fn void BView::EnableLayoutInvalidation() 4648 \brief Enable layout invalidation. 4649 4650 \remark This is only meaningful if the view is part of a BLayout. 4651 4652 \since Haiku R1 4653*/ 4654 4655 4656/*! 4657 \fn void BView::DisableLayoutInvalidation() 4658 \brief Disable layout invalidation. 4659 4660 \remark This is only meaningful if the view is part of a BLayout. 4661 4662 \since Haiku R1 4663*/ 4664 4665 4666/*! 4667 \fn bool BView::IsLayoutInvalidationDisabled() 4668 \brief Returns whether or not layout invalidation is disabled. 4669 4670 \remark This is only meaningful if the view is part of a BLayout. 4671 4672 \return \c true of layout invalidation is disabled, \c false otherwise. 4673 4674 \since Haiku R1 4675*/ 4676 4677 4678/*! 4679 \fn bool BView::IsLayoutValid() const 4680 \brief Returns whether or not the layout is valid. 4681 4682 \remark This is only meaningful if the view is part of a BLayout. 4683 4684 \returns Returns \c true if the layout is valid, \c false otherwise. 4685 4686 \since Haiku R1 4687*/ 4688 4689 4690/*! 4691 \fn void BView::ResetLayoutInvalidation() 4692 \brief Service call for BView derived classes re-enabling 4693 InvalidateLayout() notifications. 4694 4695 BLayout and BView will avoid calling InvalidateLayout on views that have 4696 already been invalidated, but if the view caches internal layout information 4697 which it updates in methods other than DoLayout(), it has to invoke this 4698 method, when it has done so, since otherwise the information might become 4699 obsolete without the layout noticing. 4700 4701 This is only meaningful if the view is part of a BLayout. 4702 4703 \since Haiku R1 4704*/ 4705 4706 4707/*! 4708 \fn BLayoutContext* BView::LayoutContext() const 4709 \brief Returns the BLayoutContext for this View. 4710 4711 \remark This is only meaningful if the view is part of a BLayout. 4712 4713 \since Haiku R1 4714*/ 4715 4716 4717/*! 4718 \fn void BView::Layout(bool force) 4719 \brief Layout the view. 4720 4721 \remark This is only meaningful if the view is part of a BLayout. 4722 4723 \param force If \c true layout even if valid. 4724 4725 \since Haiku R1 4726*/ 4727 4728 4729/*! 4730 \fn void BView::Relayout() 4731 \brief Relayout the view. 4732 4733 \remark This is only meaningful if the view is part of a BLayout. 4734 4735 \since Haiku R1 4736*/ 4737 4738 4739/*! 4740 \fn void BView::DoLayout() 4741 \brief Layout view within the layout context. 4742 4743 \remark This is only meaningful if the view is part of a BLayout. 4744 4745 \since Haiku R1 4746*/ 4747 4748 4749//! @} 4750 4751 4752/*! 4753 \name Tool Tips 4754 4755 \note These methods were not available in BeOS R5. 4756*/ 4757 4758 4759//! @{ 4760 4761 4762/*! 4763 \fn void BView::SetToolTip(const char* text) 4764 \brief Set the tool tip of the view to \a text. 4765 4766 \param text The \a text to set the view to or \c NULL or blank to unset. 4767 4768 \since Haiku R1 4769*/ 4770 4771 4772/*! 4773 \fn void BView::SetToolTip(BToolTip* tip) 4774 \brief Set the tool tip of the view to the \a tip object. 4775 4776 \param tip The tool tip object to set the view to or \c NULL to unset. 4777 4778 \since Haiku R1 4779*/ 4780 4781 4782/*! 4783 \fn BToolTip* BView::ToolTip() const 4784 \brief Return the tool tip set to the view or \c NULL if not set. 4785 4786 \return The BToolTip object set to the view. 4787 4788 \since Haiku R1 4789*/ 4790 4791 4792/*! 4793 \fn void BView::ShowToolTip(BToolTip* tip) 4794 \brief Show the tool tip at the current mouse position. 4795 4796 \param tip The BToolTip object to show. 4797 4798 \since Haiku R1 4799*/ 4800 4801 4802/*! 4803 \fn void BView::HideToolTip() 4804 \brief Hide the view's tool tip. 4805 4806 \since Haiku R1 4807*/ 4808 4809 4810/*! 4811 \fn bool BView::GetToolTipAt(BPoint point, BToolTip** _tip) 4812 \brief Point \a _tip with the view's tool tip. 4813 4814 \param point Currently unused. 4815 \param _tip A pointer to a pointer to a BToolTip object to set. 4816 4817 \since Haiku R1 4818*/ 4819 4820 4821//! @} 4822