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 it's 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*/ 286