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