docs/user/interface/Menu.dox

   1 /*
   2  * Copyright 2013 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              John Scipione, jscipione@gmail.com
   7  *
   8  * Corresponds to:
   9  *              headers/os/interface/Menu.h      hrev46321
  10  *              src/kits/interface/Menu.cpp      hrev46321
  11  */
  12
  13
  14 /*!
  15         \file Menu.h
  16         \ingroup interface
  17         \ingroup libbe
  18         \brief BMenu class definition and support structures.
  19 */
  20
  21
  22 /*!
  23         \enum menu_layout
  24         \ingroup interface
  25
  26         Constants to define the layout of the menu items in a menu.
  27
  28         \since BeOS R3
  29 */
  30
  31
  32 /*!
  33         \var menu_layout B_ITEMS_IN_ROW
  34
  35         Items are arranged in a row, one next to the other.
  36
  37         \since BeOS R3
  38 */
  39
  40
  41 /*!
  42         \var menu_layout B_ITEMS_IN_COLUMN
  43
  44         Items are arranged in a column, one on top of the other.
  45
  46         \since BeOS R3
  47 */
  48
  49
  50 /*!
  51         \var menu_layout B_ITEMS_IN_MATRIX
  52
  53         Items are arranged in a matrix, a free-form arrangement that you create.
  54
  55         \since BeOS R3
  56 */
  57
  58
  59 /*!
  60         \struct menu_info
  61         \ingroup interface
  62         \ingroup libbe
  63         \brief Information about a menu such as font size and family, background
  64                color, and flags.
  65
  66         \since BeOS R3
  67 */
  68
  69
  70 /*!
  71         \var menu_info::font_size
  72
  73         The font size to draw menu items with.
  74
  75         \since BeOS R3
  76 */
  77
  78
  79 /*!
  80         \var menu_info::f_family
  81
  82         The font family used to draw menu items.
  83
  84         \since BeOS R3
  85 */
  86
  87
  88 /*!
  89         \var menu_info::f_style
  90
  91         The font style used to draw menu items.
  92
  93         \since BeOS R3
  94 */
  95
  96
  97 /*!
  98         \var menu_info::background_color
  99
 100         The menu's background color.
 101
 102         \since BeOS R3
 103 */
 104
 105
 106 /*!
 107         \var menu_info::separator
 108
 109         The style of horizontal line to use to separates groups of items in a menu.
 110
 111         \since BeOS R3
 112 */
 113
 114
 115 /*!
 116         \var menu_info::click_to_open
 117
 118         Whether or not the menu opens on click. The default value is \c true.
 119
 120         \since BeOS R3
 121 */
 122
 123
 124 /*!
 125         \var menu_info::triggers_always_shown
 126
 127         Whether or not trigger underlines should always be shown. The default value
 128         is \c false.
 129
 130         \since BeOS R3
 131 */
 132
 133
 134 /*!
 135         \fn status_t get_menu_info(menu_info* info)
 136         \brief Fill out the menu_info struct into \a info.
 137
 138         \since BeOS R3
 139 */
 140
 141
 142 /*!
 143         \fn status_t set_menu_info(menu_info* info)
 144         \brief Set the menu's menu_info struct to \a info adjusting how the menu
 145                will look and work.
 146
 147         \since BeOS R3
 148 */
 149
 150
 151 /*!
 152         \typedef bool (*menu_tracking_hook)(BMenu* menu, void* state)
 153         \brief Defines the function passed into BMenu::SetTrackingHook().
 154
 155         \since BeOS R3
 156 */
 157
 158
 159 /*!
 160         \class BMenu
 161         \ingroup interface
 162         \ingroup libbe
 163         \brief Displays a list of menu items including additional menus
 164                arranged hierarchically.
 165
 166         A newly created BMenu object doesn't contain any menu items, you need to call
 167         AddItem() or AddList() to add some.
 168
 169         In addition to BMenuItem objects you can also add additional BMenu objects in
 170         order to create a menu hierarchy. Unlike menus in other operating systems you
 171         can always select both the submenu and menu items, although selecting the
 172         submenu might not actually produce any action other than to close the menu.
 173         The name of a submenu is used to draw its label.
 174
 175         \image html BMenu_example.png
 176
 177         BMenu is the basis of several other Interface Kit classes including BMenuBar
 178         and BPopUpMenu. See BMenu::SetRadioMode() and BMenu::SetLabelFromMarked()
 179         for additional details on how BMenu and BPopUpMenu are related.
 180
 181         Menus arrange their items in one of three possible layouts:
 182         <table>
 183                 <tr>
 184                         <td>\c B_ITEMS_IN_COLUMN</td>
 185                         <td>
 186                                 The menu items are stacked vertically in a column, one on top
 187                                 of another, as in a typical pop-up menu.
 188                         </td>
 189                 </tr>
 190                 <tr>
 191                         <td>\c B_ITEMS_IN_ROW</td>
 192                         <td>
 193                                 The menu items are laid out horizontally in a row, from end to
 194                                 end, as in a typical menu bar.
 195                         </td>
 196                 </tr>
 197                 <tr>
 198                         <td>\c B_ITEMS_IN_MATRIX</td>
 199                         <td>
 200                                 The menu items are arranged in a free-form arrangement that you
 201                                 create, such as a matrix.
 202                         </td>
 203                 </tr>
 204         </table>
 205
 206         Either \c B_ITEMS_IN_COLUMN or \c B_ITEMS_IN_ROW can be passed into the
 207         default constructor, but, you should use the constructor that allows you to
 208         set the height and width of the menu in order to utilize the
 209         \c B_ITEMS_IN_MATRIX layout.
 210
 211         Several methods will only work in some layouts as noted in the method
 212         description below.
 213
 214         \since BeOS R3
 215 */
 216
 217
 218 /*!
 219         \fn BMenu::BMenu(const char* name, menu_layout layout)
 220         \brief Creates a new menu object with the specified \a name and \a layout.
 221
 222         Don't pass \c B_ITEMS_IN_MATRIX into \a layout with this method, use
 223         BMenu::BMenu(const char* name, float width, float height) instead.
 224
 225         \param name The menu's \a name, serves as a label for submenus.
 226         \param layout The menu layout, possibilities include:
 227                - \c B_ITEMS_IN_ROW items are displayed in a single row,
 228                - \c B_ITEMS_IN_COLUMN items are displayed in a single column.
 229
 230         \since BeOS R3
 231 */
 232
 233
 234 /*!
 235         \fn BMenu::BMenu(const char* name, float width, float height)
 236         \brief Creates a new menu object with a \c B_ITEMS_IN_MATRIX layout and the
 237                specified \a name, \a width, and \a height.
 238
 239         \param name The menu's \a name, serves as a label for submenus.
 240         \param width The menu \a width.
 241         \param height The menu \a height.
 242
 243         \since BeOS R3
 244 */
 245
 246
 247 /*!
 248         \fn BMenu::BMenu(BMessage* archive)
 249         \brief Archive constructor.
 250
 251         \param archive The message data to construct the menu from.
 252
 253         \since BeOS R3
 254 */
 255
 256
 257 /*!
 258         \fn BMenu::~BMenu()
 259         \brief Destructor.
 260
 261         Also frees the memory used by any attached menu items and submenus.
 262
 263         \since BeOS R3
 264 */
 265
 266
 267 /*!
 268         \name Archiving
 269 */
 270
 271
 272 //! @{
 273
 274
 275 /*!
 276         \fn BArchivable* BMenu::Instantiate(BMessage* archive)
 277         \brief Creates a new BMenu object from an \a archive message.
 278
 279         \returns A newly created BMenu object or \c NULL if the message doesn't
 280                  contain an archived BMenu.
 281
 282         \since BeOS R3
 283 */
 284
 285
 286 /*!
 287         \fn status_t BMenu::Archive(BMessage* data, bool deep) const
 288         \brief Archives the the BMenu object into the \a data message.
 289
 290         \param data A pointer to the BMessage to archive the object into.
 291         \param deep Whether or not to archive attached menu items as well.
 292
 293         \return A status code, \c B_OK if everything went well or an error code
 294                 otherwise.
 295         \retval B_OK The object was archived successfully.
 296         \retval B_NO_MEMORY Ran out of memory while archiving the object.
 297
 298         \since BeOS R3
 299 */
 300
 301
 302 //! @}
 303
 304
 305 /*!
 306         \name Hook Methods
 307 */
 308
 309
 310 //! @{
 311
 312
 313 /*!
 314         \fn void BMenu::AttachedToWindow()
 315         \brief Lays out the menu items and resizes the menu to fit.
 316
 317         \since BeOS R3
 318 */
 319
 320
 321 /*!
 322         \fn void BMenu::Draw(BRect updateRect)
 323         \brief Draws the menu.
 324
 325         \param updateRect The area to draw in.
 326
 327         \since BeOS R3
 328 */
 329
 330
 331 /*!
 332         \fn void BMenu::MessageReceived(BMessage* message)
 333         \brief Handles a \a message received by the associated looper.
 334
 335         Responds to mouse wheel events scrolling the menu if it is too
 336         long to fit in the window. Hold \c B_SHIFT_KEY to cause the menu
 337         to scroll faster.
 338
 339         \param message The \a message received by the associated looper.
 340
 341         \since BeOS R3
 342 */
 343
 344
 345 /*!
 346         \fn void BMenu::KeyDown(const char* bytes, int32 numBytes)
 347         \brief Hook method that is called when a keyboard key is pressed.
 348
 349         Handles keyboard navigation and triggers.
 350
 351         \param bytes The bytes of the key combination pressed.
 352         \param numBytes The number of bytes in \a bytes.
 353
 354         \since BeOS R3
 355 */
 356
 357
 358 //! @}
 359
 360
 361 /*!
 362         \fn bool BMenu::AddItem(BMenuItem* item)
 363         \brief Adds a menu \a item to the end of the list.
 364
 365         \warning This method should only be used for a menu in \c B_ITEMS_IN_COLUMN
 366                  or \c B_ITEMS_IN_ROW layout, it is an error to use this method for
 367                  a menu in \c B_ITEMS_IN_MATRIX layout.
 368
 369         \param item The menu \a item to add.
 370
 371         \return Whether or not the \a item was added to the menu.
 372
 373         \since BeOS R3
 374 */
 375
 376
 377 /*!
 378         \fn bool BMenu::AddItem(BMenuItem* item, int32 index)
 379         \brief Adds a menu \a item at the specified \a index.
 380
 381         \warning This method should only be used for a menu in \c B_ITEMS_IN_COLUMN
 382                  or \c B_ITEMS_IN_ROW layout, it is an error to use this method for
 383                  a menu in \c B_ITEMS_IN_MATRIX layout.
 384
 385         \param item The menu \a item to add.
 386         \param index The \a index where to add the \a item to the menu.
 387
 388         \return Whether or not the \a item was added to the menu.
 389
 390         \since BeOS R3
 391 */
 392
 393
 394 /*!
 395         \fn bool BMenu::AddItem(BMenuItem* item, BRect frame)
 396         \brief Adds a menu \a item in the specified \a frame rectangle within the menu.
 397
 398         \warning This method should only be used for a menu in \c B_ITEMS_IN_MATRIX
 399                  layout, it is an error to use this method for a menu in
 400                  \c B_ITEMS_IN_COLUMN or \c B_ITEMS_IN_ROW layout.
 401
 402         \param item The menu \a item to add.
 403         \param frame The \a frame rectangle where to add the \a item to the menu.
 404
 405         \return Whether or not the \a item was added to the menu.
 406
 407         \since BeOS R3
 408 */
 409
 410
 411 /*!
 412         \fn bool BMenu::AddItem(BMenu* submenu)
 413         \brief Add a \a submenu to the end of the list.
 414
 415         \warning This method should only be used for a menu in \c B_ITEMS_IN_COLUMN
 416                  or \c B_ITEMS_IN_ROW layout, it is an error to use this method for
 417                  a menu in \c B_ITEMS_IN_MATRIX layout.
 418
 419         \param submenu The submenu to add.
 420
 421         \return Whether or not the \a submenu was added to the menu.
 422
 423         \since BeOS R3
 424 */
 425
 426
 427 /*!
 428         \fn bool BMenu::AddItem(BMenu* submenu, int32 index)
 429         \brief Add a \a submenu at the specified \a index.
 430
 431         \warning This method should only be used for a menu in \c B_ITEMS_IN_COLUMN
 432                  or \c B_ITEMS_IN_ROW layout, it is an error to use this method for
 433                  a menu in \c B_ITEMS_IN_MATRIX layout.
 434
 435         \param submenu The \a submenu to add.
 436         \param index The \a index where to add the \a submenu to the menu.
 437
 438         \return Whether or not the \a submenu was added to the menu.
 439
 440         \since BeOS R3
 441 */
 442
 443
 444 /*!
 445         \fn bool BMenu::AddItem(BMenu* submenu, BRect frame)
 446         \brief Adds a \a submenu in the specified \a frame rectangle within the
 447                menu.
 448
 449         \warning This method should only be used for a menu in \c B_ITEMS_IN_MATRIX
 450                  layout, it is an error to use this method for a menu in
 451                  \c B_ITEMS_IN_COLUMN or \c B_ITEMS_IN_ROW layout.
 452
 453         \param submenu The submenu to add.
 454         \param frame The \a frame rectangle where to add the submenu to the menu.
 455
 456         \return Whether or not the \a submenu was added to the menu.
 457
 458         \since BeOS R3
 459 */
 460
 461
 462 /*!
 463         \fn bool BMenu::AddList(BList* list, int32 index)
 464         \brief Add a \a list of menu items at the specified \a index.
 465
 466         \warning This method should only be used for a menu in \c B_ITEMS_IN_COLUMN
 467                  or \c B_ITEMS_IN_ROW layout, it is an error to use this method for
 468                  a menu in \c B_ITEMS_IN_MATRIX layout.
 469
 470         \param list The \a list of menu items to add.
 471         \param index The \a index where to add the \a list to the menu.
 472
 473         \return Whether or not the \a list of menu items was added to the menu.
 474
 475         \since BeOS R3
 476 */
 477
 478
 479 /*!
 480         \fn bool BMenu::AddSeparatorItem()
 481         \brief Adds a separator item to the end of the menu.
 482
 483         \warning This method should only be used for a menu in \c B_ITEMS_IN_COLUMN
 484                  layout, it is an error to use this method for a menu in
 485                  \c B_ITEMS_IN_ROW or \c B_ITEMS_IN_MATRIX layout.
 486
 487         \return Whether or not the separator item was added to the menu.
 488
 489         \since BeOS R3
 490 */
 491
 492
 493 /*!
 494         \fn bool BMenu::RemoveItem(BMenuItem* item)
 495         \brief Remove and delete the specified \a item from the menu.
 496
 497         \return Whether or not the \a item was removed from the menu.
 498
 499         \since BeOS R3
 500 */
 501
 502
 503 /*!
 504         \fn BMenuItem* BMenu::RemoveItem(int32 index)
 505         \brief Remove the item at the specified \a index from the menu.
 506
 507         The menu item object is not deleted.
 508
 509         \warning This method should only be used for a menu in \c B_ITEMS_IN_COLUMN
 510                  or \c B_ITEMS_IN_ROW layout, it is an error to use this method for
 511                  a menu in \c B_ITEMS_IN_MATRIX layout.
 512
 513         \param index The \a index of where to remove the menu item.
 514
 515         \return The menu item object or \c NULL if not found.
 516
 517         \since BeOS R3
 518 */
 519
 520
 521 /*!
 522         \fn bool BMenu::RemoveItems(int32 index, int32 count, bool deleteItems)
 523         \brief Remove \a count number of items from the menu starting at the specified
 524                \a index and delete them if \a deleteItems is \c true.
 525
 526         \warning This method should only be used for a menu in \c B_ITEMS_IN_COLUMN
 527                  or \c B_ITEMS_IN_ROW layout, it is an error to use this method for
 528                  a menu in \c B_ITEMS_IN_MATRIX layout.
 529
 530         \param index The \a index of where to start removing menu items.
 531         \param count The number of items to remove.
 532         \param deleteItems Whether or not to delete the items after removing them.
 533
 534         \return Whether or not the items were removed from the menu.
 535
 536         \since BeOS R3
 537 */
 538
 539
 540 /*!
 541         \fn bool BMenu::RemoveItem(BMenu* submenu)
 542         \brief Remove and delete a \a submenu from the menu.
 543
 544         \param submenu The submenu to remove.
 545
 546         \return Whether or not the \a submenu was removed from the menu.
 547
 548         \since BeOS R3
 549 */
 550
 551
 552 /*!
 553         \fn int32 BMenu::CountItems() const
 554         \brief Returns the number of items added to the menu.
 555
 556         \return The number of items added to the menu.
 557
 558         \since BeOS R3
 559 */
 560
 561
 562 /*!
 563         \fn BMenuItem* BMenu::ItemAt(int32 index) const
 564         \brief Returns a pointer to the menu item at the specified \a index.
 565
 566         \warning This method should only be used for a menu in \c B_ITEMS_IN_COLUMN
 567                  or \c B_ITEMS_IN_ROW layout, it is an error to use this method for
 568                  a menu in \c B_ITEMS_IN_MATRIX layout.
 569
 570         \return A pointer to a menu item or \c NULL if not found.
 571
 572         \since BeOS R3
 573 */
 574
 575
 576 /*!
 577         \fn BMenu* BMenu::SubmenuAt(int32 index) const
 578         \brief Returns a pointer to a submenu at the specified \a index.
 579
 580         \warning This method should only be used for a menu in \c B_ITEMS_IN_COLUMN
 581                  or \c B_ITEMS_IN_ROW layout, it is an error to use this method for a
 582                  menu in \c B_ITEMS_IN_MATRIX layout.
 583
 584         \return A pointer to a submenu or \c NULL if not found.
 585
 586         \since BeOS R3
 587 */
 588
 589
 590 /*!
 591         \fn int32 BMenu::IndexOf(BMenuItem* item) const
 592         \brief Returns the index of the specified menu \a item.
 593
 594         The index starts at the left for a menu in \c B_ITEMS_IN_COLUMN layout going
 595         right or start at the top for a menu in \c B_ITEMS_IN_ROW layout going down.
 596
 597         \warning This method should only be used for a menu in \c B_ITEMS_IN_COLUMN
 598                  or \c B_ITEMS_IN_ROW layout, it is an error to use this method for
 599                  a menu in \c B_ITEMS_IN_MATRIX layout.
 600
 601         \return The index of the menu \a item or \c B_ERROR of not found.
 602
 603         \since BeOS R3
 604 */
 605
 606
 607 /*!
 608         \fn int32 BMenu::IndexOf(BMenu* submenu) const
 609         \brief Returns the index of the specified \a submenu.
 610
 611         The index starts at the left for a menu in \c B_ITEMS_IN_COLUMN layout going
 612         right or at the top for a menu in \c B_ITEMS_IN_ROW layout going down.
 613
 614         \warning This method should only be used for a menu in \c B_ITEMS_IN_COLUMN
 615                  or \c B_ITEMS_IN_ROW layout, it is an error to use this method for
 616                  a menu in \c B_ITEMS_IN_MATRIX layout.
 617
 618         \return The index of the \a submenu or \c B_ERROR of not found.
 619
 620         \since BeOS R3
 621 */
 622
 623
 624 /*!
 625         \fn BMenuItem* BMenu::FindItem(const char* label) const
 626         \brief Returns a pointer to the menu item with the specified \a label.
 627
 628         \param label The \a label of the menu item to find.
 629
 630         \return A pointer to a menu item or \c NULL if not found.
 631
 632         \since BeOS R3
 633 */
 634
 635
 636 /*!
 637         \fn BMenuItem* BMenu::FindItem(uint32 command) const
 638         \brief Returns a pointer to the menu item with the specified \a command for
 639                its associated message.
 640
 641         \param command The \a command of the associated message of the menu item to
 642                find.
 643
 644         \return A pointer to a menu item or \c NULL if not found.
 645
 646         \since BeOS R3
 647 */
 648
 649
 650 /*!
 651         \fn status_t BMenu::SetTargetForItems(BHandler* handler)
 652         \brief Set the target to \a handler for each item in the menu.
 653
 654         This is a convenient way to set the target for all the items in a menu.
 655
 656         \param handler The BHandler object to set the target of the menu item to.
 657
 658         This method doesn't descend into submenus recursively and only acts on items
 659         that have already been added to the menu.
 660
 661         \return \c B_OK on success or an error code on error.
 662
 663         \since BeOS R3
 664 */
 665
 666
 667 /*!
 668         \fn status_t BMenu::SetTargetForItems(BMessenger messenger)
 669         \brief Set the target to \a messenger for each item in the menu.
 670
 671         This is a convenient way to set the target for all the items in a menu.
 672
 673         This method doesn't descend into submenus recursively and only acts on items
 674         that have already been added to the menu.
 675
 676         \param messenger The BMessenger object to set the target of the menu item
 677                          to.
 678
 679         \return \c B_OK on success or an error code on error.
 680
 681         \since BeOS R3
 682 */
 683
 684
 685 /*!
 686         \fn void BMenu::SetEnabled(bool enable)
 687         \brief Enables or disables the menu.
 688
 689         \param enable \c true to enable, \c false to disable.
 690
 691         \since BeOS R3
 692 */
 693
 694
 695 /*!
 696         \fn void BMenu::SetRadioMode(bool on)
 697         \brief Turns radio mode on or off.
 698
 699         Turning radio mode off also turns off label-from-marked mode.
 700
 701         Radio mode means that only one menu item can be set as marked at a time.
 702         Marking a menu item automatically unmarks all other menu items and draws
 703         a check mark on the left side of the marked menu item. You don't have to
 704         call BMenuItem::SetMarked() yourself for a menu in radio mode, this is done
 705         for you automatically.
 706
 707         Radio mode does not work recursively, only the current menu is considered.
 708         If you want to make a menu work in radio mode recursively you'll have to
 709         turn radio mode off and iterate through each menu marking and unmarking
 710         the items yourself.
 711
 712         \param on \c true to turn radio mode on, \c false to turn it off.
 713
 714         \since BeOS R3
 715 */
 716
 717
 718 /*!
 719         \fn void BMenu::SetTriggersEnabled(bool enable)
 720         \brief Enables or disables triggers.
 721
 722         \param enable \c true to enable triggers, \c false to disable triggers.
 723
 724         \since BeOS R3
 725 */
 726
 727
 728 /*!
 729         \fn void BMenu::SetMaxContentWidth(float width)
 730         \brief Sets the maximum width of the menu items' content area.
 731
 732         This is the maximum width that a menu item can draw in. Note that menu
 733         items have built-in margins on the left and right sides that are not
 734         included as part of the maximum content width.
 735
 736         \param width The maximum width for the menu item contents to draw in.
 737
 738         \since BeOS R3
 739 */
 740
 741
 742 /*!
 743         \fn void BMenu::SetLabelFromMarked(bool on)
 744         \brief Sets whether or not the label of the menu is set according to the
 745                marked item.
 746
 747         Turning label-from-marked mode on also turns radio mode on.
 748
 749         \param on \c true to turn label-from-marked mode on, \c false to turn it
 750                   off.
 751
 752         \since BeOS R3
 753 */
 754
 755
 756 /*!
 757         \fn bool BMenu::IsLabelFromMarked()
 758         \brief Returns whether or not the menu is in label-from-marked mode.
 759
 760         \return \c true if menu is in label-from-marked mode, \c false if not.
 761
 762         \since BeOS R3
 763 */
 764
 765
 766 /*!
 767         \fn bool BMenu::IsEnabled() const
 768         \brief Returns whether or not the menu is enabled.
 769
 770         \return \c true if menu is enabled, \c false if it is disabled.
 771
 772         \since BeOS R3
 773 */
 774
 775
 776 /*!
 777         \fn bool BMenu::IsRadioMode() const
 778         \brief Returns whether or not the menu is in radio mode.
 779
 780         \return \c true if menu is in radio mode, \c false if not.
 781
 782         \since BeOS R3
 783 */
 784
 785
 786 /*!
 787         \fn bool BMenu::AreTriggersEnabled() const
 788         \brief Returns whether or not triggers are enabled.
 789
 790         \return \c true if triggers are enabled, \c false if triggers are disabled.
 791
 792         \since BeOS R3
 793 */
 794
 795
 796 /*!
 797         \fn bool BMenu::IsRedrawAfterSticky() const
 798         \brief Returns whether or not the menu is in redraw-after-sticky mode.
 799
 800         \return \c true if menu is in redraw-after-sticky mode, \c false if not.
 801
 802         \since Haiku R1
 803 */
 804
 805
 806 /*!
 807         \fn float BMenu::MaxContentWidth() const
 808         \brief Return the maximum width of the menu items' content area.
 809
 810         \return The maximum width of the menu items' content area as a float.
 811
 812         \sa SetMaxContentWidth()
 813
 814         \since BeOS R3
 815 */
 816
 817
 818 /*!
 819         \fn BMenuItem* BMenu::FindMarked()
 820         \brief Return a pointer to the first marked menu item.
 821
 822         The index starts at the left for a menu in \c B_ITEMS_IN_COLUMN layout going
 823         right or at the top for a menu in \c B_ITEMS_IN_ROW layout going down.
 824
 825         \warning This method should only be used for a menu in \c B_ITEMS_IN_COLUMN
 826                  or \c B_ITEMS_IN_ROW layout, it is an error to use this method for
 827                  a menu in \c B_ITEMS_IN_MATRIX layout.
 828
 829         \return A pointer to the first marked menu item or \c NULL if not found.
 830
 831         \since BeOS R3
 832 */
 833
 834
 835 /*!
 836         \fn int32 BMenu::FindMarkedIndex()
 837         \brief Return the index of the first marked menu item.
 838
 839         The index starts at the left for a menu in \c B_ITEMS_IN_COLUMN layout going
 840         right or at the top for a menu in \c B_ITEMS_IN_ROW layout going down.
 841
 842         \warning This method should only be used for a menu in \c B_ITEMS_IN_COLUMN
 843                  or \c B_ITEMS_IN_ROW layout, it is an error to use this method for
 844                  a menu in \c B_ITEMS_IN_MATRIX layout.
 845
 846         \return The index of the first marked menu item or -1 if not found.
 847
 848         \since Haiku R1
 849 */
 850
 851
 852 /*!
 853         \fn BMenu* BMenu::Supermenu() const
 854         \brief Returns the pointer to the menu that this menu it attached to.
 855
 856         \return A pointer to a BMenu object or \c NULL if not found.
 857
 858         \since BeOS R3
 859 */
 860
 861
 862 /*!
 863         \fn BMenuItem* BMenu::Superitem() const
 864         \brief Returns the pointer to the menu item that this menu it attached to.
 865
 866         \return A pointer to a BMenuItem object or \c NULL if not found.
 867
 868         \since BeOS R3
 869 */
 870
 871
 872 /*!
 873         \fn BMenu::BMenu(BRect frame, const char* name, uint32 resizingMode,
 874                 uint32 flags, menu_layout layout, bool resizeToFit)
 875         \brief Implemented by derived classes to create a new menu object.
 876
 877         This method is intended to be used by derived classes that don't simply wish
 878         to utilize different sorts of menu items or arrange them in a different way,
 879         but wish to invent a different kind of menu altogether.
 880
 881         If the \a layout is set to \c B_ITEMS_IN_MATRIX the \a resizeToFit flag should
 882         be set to \c false.
 883
 884         \param frame The \a frame rectangle to create the menu in.
 885         \param name The menu's \a name, serves as a label for submenus.
 886         \param resizingMode The resizing mode flags, see BView for more details.
 887         \param flags The view \a flags, see BView for more details.
 888         \param layout The menu layout, possibilities include:
 889                - \c B_ITEMS_IN_ROW items are displayed in a single row,
 890                - \c B_ITEMS_IN_COLUMN items are displayed in a single column,
 891                - \c B_ITEMS_IN_MATRIX items are displayed in a custom matrix.
 892         \param resizeToFit Whether or not the menu should automatically resize
 893                itself to fit its contents, this will not work in
 894                \c B_ITEMS_IN_MATRIX layout.
 895
 896         \since BeOS R3
 897 */
 898
 899
 900 /*!
 901         \fn void BMenu::SetItemMargins(float left, float top, float right,
 902                 float bottom)
 903         \brief Set the menu item margins.
 904
 905         \param left The left margin to set.
 906         \param top The top margin to set.
 907         \param right The right margin to set.
 908         \param bottom The bottom margin to set.
 909
 910         \since BeOS R3
 911 */
 912
 913
 914 /*!
 915         \fn void BMenu::GetItemMargins(float* _left, float* _top, float* _right,
 916                 float* _bottom) const
 917         \brief Fill out the margins into the passed in float pointers.
 918
 919         \param _left The left margin to fill out, can be \c NULL.
 920         \param _top The top margin to fill out, can be \c NULL.
 921         \param _right The right margin to fill out, can be \c NULL.
 922         \param _bottom The bottom margin to fill out, can be \c NULL.
 923
 924         \since BeOS R3
 925 */
 926
 927
 928 /*!
 929         \fn menu_layout BMenu::Layout() const
 930         \brief Returns the current menu_layout constant.
 931
 932         \since BeOS R3
 933 */
 934
 935
 936 /*!
 937         \fn BMenuItem* BMenu::Track(bool sticky, BRect* clickToOpenRect)
 938         \brief Initiates tracking the cursor within the menu.
 939
 940         This method passes tracking control to submenus hierarchically depending on
 941         where the user moves their mouse.
 942
 943         You only need to call this method yourself if you are implementing a menu
 944         that needs to track the cursor under nonstandard circumstances.
 945
 946         \param sticky If \c true Track() leaves the menu open even after the mouse
 947                button is no longer held down.
 948         \param clickToOpenRect If \a sticky is \c true, leave the menu open even if
 949                the user releases the mouse button while the cursor is inside
 950                    \a clickToOpenRect.
 951
 952         \return A BMenuItem object if the user ends tracking by invoking an item or
 953                 \c NULL if the user didn't invoke an item.
 954
 955         \since BeOS R3
 956 */
 957
 958
 959 /*!
 960         \fn bool BMenu::AddDynamicItem(add_state state)
 961         \brief Implemented by subclasses to Add a dynamic item to the menu.
 962
 963         \param state Possibilities include:
 964                - \c B_INITIAL_ADD,
 965                - \c B_PROCESSING,
 966                - \c B_ABORT
 967
 968         \return \c true if the dynamic item was added, \c false otherwise.
 969
 970         \since Haiku R1
 971 */
 972
 973
 974 /*!
 975         \fn void BMenu::DrawBackground(BRect updateRect)
 976         \brief Draw the menu background within the bounds of \a updateRect.
 977
 978         \param updateRect The area to draw the background in.
 979
 980         \since Haiku R1
 981 */
 982
 983
 984 /*!
 985         \fn void BMenu::SetTrackingHook(menu_tracking_hook func, void* state)
 986         \brief Sets a hook function that is called when tracking begins.
 987
 988         \param func The hook function to call.
 989         \param state A variable passed to the hook function.
 990
 991         \since Haiku R1
 992 */