docs/user/interface/MenuBar.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/MenuBar.h   hrev46323
  10  *              src/kits/interface/MenuBar.cpp   hrev46323
  11  */
  12
  13
  14 /*!
  15         \file MenuBar.h
  16         \ingroup interface
  17         \ingroup libbe
  18         \brief BMenuBar class definition and support structures.
  19 */
  20
  21
  22 /*!
  23         \enum menu_bar_border
  24         \ingroup interface
  25
  26         Menu bar border style constants.
  27
  28         \see BMenuBar::SetBorder()
  29
  30         \since BeOS R3
  31 */
  32
  33
  34 /*!
  35         \var menu_bar_border B_BORDER_FRAME
  36
  37         The border is drawn around the entire menu bar.
  38
  39         \since BeOS R3
  40 */
  41
  42
  43 /*!
  44         \var menu_bar_border B_BORDER_CONTENTS
  45
  46         The border is drawn around the list of items.
  47
  48         \since BeOS R3
  49 */
  50
  51
  52 /*!
  53         \var menu_bar_border B_BORDER_EACH_ITEM
  54
  55         The border is drawn around each individual item.
  56
  57         \since BeOS R3
  58 */
  59
  60
  61 /*!
  62         \class BMenuBar
  63         \ingroup interface
  64         \ingroup libbe
  65         \brief A window's root menu.
  66
  67         A menu bar, if a window has one, is typically drawn across the top of the
  68         window just below the tab and a window typically has just a single menu bar,
  69         although this is up to you.
  70
  71         One menu bar attached to a window is considered to be the "key" menu bar
  72         that can be navigated by the user using the keyboard. The last menu bar
  73         attached to a window is automatically set as the key menu bar for the
  74         window. To override this behavior and set a different key menu bar use the
  75         BWindow::SetKeyMenuBar() method.
  76
  77         When either the \key{Menu} key or \key{Command}+\key{Esc} keys are pressed
  78         the key menu bar opens and focuses its first menu item, typically a BMenu.
  79         Once the menu bar is open the user can navigate around the attached menus
  80         and menu items using the arrow keys.
  81
  82         Like a BMenu, a BMenuBar object starts without any items attached to it,
  83         you'll need to call AddItem() or AddList() to add some. The top-level items
  84         in a menu bar are typically menus which have menu items and menus added to
  85         them in turn.
  86
  87         \since BeOS R3
  88 */
  89
  90
  91 /*!
  92         \fn BMenuBar::BMenuBar(BRect frame, const char* name, uint32 resizingMode,
  93                 menu_layout layout, bool resizeToFit)
  94         \brief Create a new BMenuBar object.
  95
  96         The default resizing mode, \c B_FOLLOW_LEFT_RIGHT | \c B_FOLLOW_TOP is
  97         meant to be used by a typical menu bar that is positioned along the top
  98         edge of a window. This resizing mode allows the menu bar to resize itself
  99         based on changes to the window's width while keeping it attached to the
 100         top of the window frame.
 101
 102         For menu bars in \c B_ITEMS_IN_ROW layout the height is automatically
 103         set to be the height of a single item, while menus bars in
 104         \c B_ITEMS_IN_COLUMN layout the width is automatically set to be the width
 105         of the widest item.
 106
 107         The width of a menu bar is set equal to the width of its parent for menu
 108         bars in \c B_ITEMS_IN_ROW layout and a \a resizingMode mask that includes
 109         \c B_FOLLOW_LEFT_RIGHT so that the menu bar will always be as wide as its
 110         attached window.
 111
 112         Likewise, the height of a menu bar is set equal to the height of its parent
 113         for menu bars in \c B_ITEMS_IN_COLUMN layout and a \a resizingMode mask that
 114         includes \c B_FOLLOW_TOP_BOTTOM so that the menu bar will always be as high
 115         as its attached window.
 116
 117         When \a resizeToFit is set to \c true, as is the default, the \a frame
 118         rectangle determines only where the menu bar is located, not its size.
 119         If the \a layout is set to \c B_ITEMS_IN_MATRIX the \a resizeToFit flag
 120         should be set to \c false.
 121
 122         \param frame The \a frame rectangle to create the menu bar in.
 123         \param name The \a name of the menu bar, used internally only.
 124         \param resizingMode The resizing mode flags, see BView for more details.
 125         \param layout The menu layout, possibilities include:
 126                - \c B_ITEMS_IN_ROW items are displayed in a single row,
 127                - \c B_ITEMS_IN_COLUMN items are displayed in a single column,
 128                - \c B_ITEMS_IN_MATRIX items are displayed in a custom matrix.
 129         \param resizeToFit Whether or not the menu bar should automatically resize
 130                itself to fit its contents, this will not work in
 131                \c B_ITEMS_IN_MATRIX layout.
 132
 133         \since BeOS R3
 134 */
 135
 136
 137 /*!
 138         \fn BMenuBar::BMenuBar(const char* name, menu_layout layout, uint32 flags)
 139         \brief Create a new BMenuBar object suitable to use with the layout APIs.
 140
 141         \param name The \a name of the menu bar, used internally only.
 142         \param flags The view \a flags, see BView for more details.
 143         \param layout The menu layout, possibilities include:
 144                - \c B_ITEMS_IN_ROW items are displayed in a single row,
 145                - \c B_ITEMS_IN_COLUMN items are displayed in a single column,
 146                - \c B_ITEMS_IN_MATRIX items are displayed in a custom matrix.
 147
 148         \since Haiku R1
 149 */
 150
 151
 152 /*!
 153         \fn BMenuBar::BMenuBar(BMessage* archive)
 154         \brief Archive constructor.
 155
 156         \param archive The message data to construct the menu from.
 157
 158         \since BeOS R3
 159 */
 160
 161
 162 /*!
 163         \fn BMenuBar::~BMenuBar()
 164         \brief Destructor.
 165
 166         Also frees the memory used by any attached menus and menu items.
 167
 168         \since BeOS R3
 169 */
 170
 171
 172 /*!
 173         \name Archiving
 174 */
 175
 176
 177 //! @{
 178
 179
 180 /*!
 181         \fn BArchivable* BMenuBar::Instantiate(BMessage* data)
 182         \brief Creates a new BMenuBar object from an \a archive message.
 183
 184         \returns A newly created BMenuBar object or \c NULL if the message
 185                  doesn't contain an archived BMenuBar.
 186
 187         \since BeOS R3
 188 */
 189
 190
 191 /*!
 192         \fn status_t BMenuBar::Archive(BMessage* data, bool deep) const
 193         \brief Archives the the BMenuBar object into the \a data message.
 194
 195         \param data A pointer to the BMessage to archive the object into.
 196         \param deep Whether or not to archive attached menu items as well.
 197
 198         \return A status code, \c B_OK if everything went well or an error code
 199                 otherwise.
 200         \retval B_OK The object was archived successfully.
 201         \retval B_NO_MEMORY Ran out of memory while archiving the object.
 202
 203         \since BeOS R3
 204 */
 205
 206
 207 //! @}
 208
 209
 210 /*!
 211         \name Hook Methods
 212 */
 213
 214
 215 //! @{
 216
 217
 218 /*!
 219         \fn void BMenuBar::AttachedToWindow()
 220         \brief Sets this as the key menubar for the window, lays out the menu items
 221                and resizes the menu to fit.
 222
 223         \see BWindow::SetKeyMenuBar()
 224
 225         \since BeOS R3
 226 */
 227
 228
 229 /*!
 230         \fn void BMenuBar::FrameResized(float newWidth, float newHeight)
 231         \brief Hook method that gets called when the menu bar is resized.
 232
 233         Redraws the affected borders.
 234
 235         \copydetails BView::FrameResized()
 236 */
 237
 238
 239 /*!
 240         \fn void BMenuBar::Draw(BRect updateRect)
 241         \brief Draws the menu bar.
 242
 243         \param updateRect The area to draw in.
 244
 245         \since BeOS R3
 246 */
 247
 248
 249 /*!
 250         \fn void BMenuBar::MouseDown(BPoint where)
 251         \brief Hook method that is called when a mouse button is pressed.
 252
 253         Right clicking on a menu bar sends the window to back or brings it to front.
 254
 255         \copydetails BView::MouseDown()
 256 */
 257
 258
 259 //! @}
 260
 261
 262 /*!
 263         \fn void BMenuBar::SetBorder(menu_bar_border border)
 264         \brief Specifies how the menu bar border is drawn.
 265
 266         The default is \c B_BORDER_FRAME.
 267
 268         \param border Options include:
 269                - \c B_BORDER_FRAME The border is drawn around the entire menu bar.
 270                - \c B_BORDER_CONTENTS The border is drawn around the list of items.
 271                - \c B_BORDER_EACH_ITEM The border is drawn around each individual
 272                     item.
 273
 274         \since BeOS R3
 275 */
 276
 277
 278 /*!
 279         \fn menu_bar_border BMenuBar::Border() const
 280         \brief Returns the currently set border style.
 281
 282         \see BMenuBar::SetBorder() for details.
 283
 284         \since BeOS R3
 285 */