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/PopUpMenu.h hrev46360 10 * src/kits/interface/PopUpMenu.cpp hrev46360 11 */ 12 13 14/*! 15 \file PopUpMenu.h 16 \ingroup interface 17 \ingroup libbe 18 \brief BPopUpMenu class definition and support structures. 19*/ 20 21 22/*! 23 \class BPopUpMenu 24 \ingroup interface 25 \ingroup libbe 26 \brief Displays a pop-up menu. 27 28 A BPopUpMenu is typically used to display a limited set of 29 mutually-exclusive choices rather than as part of a deeply nested 30 menu hierarchy. A BPopUpMenu is similar to a BMenu but has a few 31 additional methods to make it easier to use the menu as a stand-alone 32 menu and to manage the object's lifetime. 33 34 Pop-up menus are used either as a stand-alone menu, usually as 35 a context menu activated by \c B_SECONDARY_MOUSE_BUTTON, or 36 as a menu attached to a BMenuField or BMenuBar. 37 38 If the pop-up menu is used as a stand-alone menu, the Go() method 39 controls how and where the menu pops up and provides several options 40 for how the pop-up menu works. 41 42 Once Go() returns the BPopUpMenu object should be destroyed. You can call 43 SetAsyncAutoDestruct() passing \c true to destroy the object automatically 44 when it returns. This is not advisable if the \a deliversMessage parameter 45 of Go() is set \c false because you'll want to examine the return value 46 before destroying the BPopUpMenu object. 47 48 If the pop-up menu is used as part of a BMenuField or BMenuBar it behaves 49 almost exactly like a BMenu would, but, the menu pops up directly under the 50 mouse pointer instead of underneath the BMenuBar or BMenuField. 51 52 \since BeOS R3 53*/ 54 55 56/*! 57 \fn BPopUpMenu::BPopUpMenu(const char* name, bool radioMode, 58 bool labelFromMarked, menu_layout layout) 59 \brief Creates a new BPopUpMenu object. 60 61 \attention A BPopUpMenu should never be set to \a B_ITEMS_IN_MATRIX 62 layout. The menu is automatically resized so that its 63 menu items will fit exactly in the menu. 64 65 \param name The menu's name, serves as a label for submenus. 66 \param radioMode Whether or not the menu is in radio mode, default is 67 \c true. 68 \param labelFromMarked Whether or not the menu is in label-from-marked mode, 69 default is \c true. 70 \param layout The menu layout, possibilities include: 71 - \c B_ITEMS_IN_ROW items are displayed in a single row, 72 - \c B_ITEMS_IN_COLUMN items are displayed in a single column, 73 the default layout. 74 75 \see BMenu::SetRadioMode() 76 \see BMenu::SetLabelFromMarked() 77 78 \since BeOS R3 79*/ 80 81 82/*! 83 \fn BPopUpMenu::BPopUpMenu(BMessage* archive) 84 \brief Archive constructor. 85 86 \param archive The message data to construct the pop-up menu from. 87 88 \since BeOS R3 89*/ 90 91 92/*! 93 \fn BPopUpMenu& BPopUpMenu::operator=(const BPopUpMenu& other) 94 \brief Assignment overload method. 95 96 \param other The BPopUpMenu object to assign from. 97 98 \return The newly assigned BPopUpMenu object. 99 100 \since BeOS R3 101*/ 102 103 104/*! 105 \fn BPopUpMenu::~BPopUpMenu() 106 \brief Destructor method. 107 108 Also frees the memory used by any attached menu items. 109 110 \since BeOS R3 111*/ 112 113 114/*! 115 \name Archiving 116*/ 117 118 119//! @{ 120 121 122/*! 123 \fn status_t BPopUpMenu::Archive(BMessage* data, bool deep) const 124 \brief Archives the the BMenuField object into the \a data message. 125 126 \param data A pointer to the BMessage to archive the object into. 127 \param deep Whether or not to archive attached menu items as well. 128 129 \return A status code, \c B_OK if everything went well or an error code 130 otherwise. 131 \retval B_OK The object was archived successfully. 132 \retval B_NO_MEMORY Ran out of memory while archiving the object. 133 134 \since BeOS R3 135*/ 136 137 138/*! 139 \fn BArchivable* BPopUpMenu::Instantiate(BMessage* data) 140 \brief Creates a new BPopUpMenu object from the \a data message. 141 142 \returns A newly created BPopUpMenu object or \c NULL if the message 143 doesn't contain an archived BPopUpMenu. 144 145 \since BeOS R3 146*/ 147 148 149//! @} 150 151 152/*! 153 \fn BMenuItem* BPopUpMenu::Go(BPoint where, bool deliversMessage, 154 bool openAnyway, bool async) 155 \brief Places the menu on screen. 156 157 \param where The location to open the left-top-corner of the pop-up menu 158 in the screen's coordinate system. 159 \param deliversMessage if \c true, the menu item posts a message to its 160 target as it normally would when selected by the user. 161 If \a deliversMessage is \c false no message is sent and you are 162 expected to decide what action to take based on the return value. 163 \param openAnyway If \c true, the pop-up menu will stay open even once the 164 user has released the mouse button. To dismiss the menu, either a 165 menu item must be selected or it must be dismissed programmatically. 166 \param async If \c true the menu will return \c NULL immediately, if 167 \c false the menu will not return until a menu item is selected 168 or it is dismissed by the user. If a menu item was selected a 169 pointer to the menu item is returned, if not, \c NULL is returned. 170 171 \since BeOS R3 172*/ 173 174 175/*! 176 \fn BMenuItem* BPopUpMenu::Go(BPoint where, bool deliversMessage, 177 bool openAnyway, BRect clickToOpen, bool async) 178 \brief Places the menu on screen, with \a clickToOpen option. 179 180 The \a clickToOpen rectangle should be specified in the screen's 181 coordinate system. \a openAnyway must be set \c true for the \a clickToOpen 182 rectangle to work. 183 184 \param where The location to open the left-top-corner of the pop-up menu 185 in the screen's coordinate system. 186 \param deliversMessage if \c true, the menu item posts a message to its 187 target as it normally would when selected by the user. 188 If \a deliversMessage is \c false no message is sent and you are 189 expected to decide what action to take based on the return value. 190 \param openAnyway If \c true, the pop-up menu will stay open even once the 191 user has released the mouse button. To dismiss the menu, either a 192 menu item must be selected or it must be dismissed programmatically. 193 \param clickToOpen If the user releases the mouse button while the cursor 194 is inside the \a clickToOpen rectangle the menu is kept on-screen, 195 if the cursor is located outside of the \a clickToOpen rectangle 196 the menu is removed from the screen and Go() returns. 197 \param async If \c true the menu will return \c NULL immediately, if 198 \c false the menu will not return until a menu item is selected 199 or it is dismissed by the user. If a menu item was selected a 200 pointer to the menu item is returned, if not, \c NULL is returned. 201 202 \since BeOS R3 203*/ 204 205 206/*! 207 \fn void BPopUpMenu::SetAsyncAutoDestruct(bool on) 208 \brief Indicates whether or not the BPopUpMenu will delete itself after 209 closing, async-auto-destruct mode is set to \c false by default. 210 211 \param on \c true to turn async-auto-destruct mode on, \c false to turn 212 async-auto-destruct mode off. 213 214 \since BeOS R5 215*/ 216 217 218/*! 219 \fn bool BPopUpMenu::AsyncAutoDestruct() const 220 \brief Returns the current async-auto-destruct setting. 221 222 \return \c true if async-auto-destruct mode is turned on, \c false if 223 async-auto-destruct mode is turned off. 224 225 \see SetAsyncAutoDestruct() 226 227 \since BeOS R5 228*/ 229 230 231/*! 232 \fn BPoint BPopUpMenu::ScreenLocation() 233 \brief Returns where the pop-up menu will appear on screen when it is 234 opened. 235 236 You can override this method in your BPopUpMenu derived class to return 237 where the pop-up menu will appear on screen. 238 239 \returns The location that the pop-up-menu will appear on screen in the 240 screen's coordinate system. 241 242 \since BeOS R3 243*/ 244