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 53 54/*! 55 \fn BPopUpMenu::BPopUpMenu(const char* name, bool radioMode, 56 bool labelFromMarked, menu_layout layout) 57 \brief Creates a new BPopUpMenu object. 58 59 \attention A BPopUpMenu should never be set to \a B_ITEMS_IN_MATRIX 60 layout. The menu is automatically resized so that its 61 menu items will fit exactly in the menu. 62 63 \param name The menu's name, serves as a label for submenus. 64 \param radioMode Whether or not the menu is in radio mode, default is 65 \c true. 66 \param labelFromMarked Whether or not the menu is in label-from-marked mode, 67 default is \c true. 68 \param layout The menu layout, possibilities include: 69 - \c B_ITEMS_IN_ROW items are displayed in a single row, 70 - \c B_ITEMS_IN_COLUMN items are displayed in a single column, 71 the default layout. 72 73 \see BMenu::SetRadioMode() 74 \see BMenu::SetLabelFromMarked() 75*/ 76 77 78/*! 79 \fn BPopUpMenu::BPopUpMenu(BMessage* archive) 80 \brief Archive constructor. 81 82 \param archive The message data to construct the pop-up menu from. 83*/ 84 85 86/*! 87 \fn BPopUpMenu::~BPopUpMenu() 88 \brief Destructor method. 89 90 Also frees the memory used by any attached menu items. 91*/ 92 93 94/*! 95 \fn status_t BPopUpMenu::Archive(BMessage* data, bool deep) const 96 \brief Archives the the BMenuField object into the \a data message. 97 98 \param data A pointer to the BMessage to archive the object into. 99 \param deep Whether or not to archive attached menu items as well. 100 101 \return A status code, \c B_OK if everything went well or an error code 102 otherwise. 103 \retval B_OK The object was archived successfully. 104 \retval B_NO_MEMORY Ran out of memory while archiving the object. 105*/ 106 107 108/*! 109 \fn BArchivable* BPopUpMenu::Instantiate(BMessage* data) 110 \brief Creates a new BPopUpMenu object from the \a data message. 111 112 \returns A newly created BPopUpMenu object or \c NULL if the message 113 doesn't contain an archived BPopUpMenu. 114*/ 115 116 117/*! 118 \fn BMenuItem* BPopUpMenu::Go(BPoint where, bool deliversMessage, 119 bool openAnyway, bool async) 120 \brief Places the menu on screen. 121 122 \param where The location to open the left-top-corner of the pop-up menu 123 in the screen's coordinate system. 124 \param deliversMessage if \c true, the menu item posts a message to its 125 target as it normally would when selected by the user. 126 If \a deliversMessage is \c false no message is sent and you are 127 expected to decide what action to take based on the return value. 128 \param openAnyway If \c true, the pop-up menu will stay open even once the 129 user has released the mouse button. To dismiss the menu, either a 130 menu item must be selected or it must be dismissed programmatically. 131 \param async If \c true the menu will return \c NULL immediately, if 132 \c false the menu will not return until a menu item is selected 133 or it is dismissed by the user. If a menu item was selected a 134 pointer to the menu item is returned, if not, \c NULL is returned. 135*/ 136 137 138/*! 139 \fn BMenuItem* BPopUpMenu::Go(BPoint where, bool deliversMessage, 140 bool openAnyway, BRect clickToOpen, bool async) 141 \brief Places the menu on screen, with \a clickToOpen option. 142 143 The \a clickToOpen rectangle should be specified in the screen's 144 coordinate system. \a openAnyway must be set \c true for the \a clickToOpen 145 rectangle to work. 146 147 \param where The location to open the left-top-corner of the pop-up menu 148 in the screen's coordinate system. 149 \param deliversMessage if \c true, the menu item posts a message to its 150 target as it normally would when selected by the user. 151 If \a deliversMessage is \c false no message is sent and you are 152 expected to decide what action to take based on the return value. 153 \param openAnyway If \c true, the pop-up menu will stay open even once the 154 user has released the mouse button. To dismiss the menu, either a 155 menu item must be selected or it must be dismissed programmatically. 156 \param clickToOpen If the user releases the mouse button while the cursor 157 is inside the \a clickToOpen rectangle the menu is kept on-screen, 158 if the cursor is located outside of the \a clickToOpen rectangle 159 the menu is removed from the screen and Go() returns. 160 \param async If \c true the menu will return \c NULL immediately, if 161 \c false the menu will not return until a menu item is selected 162 or it is dismissed by the user. If a menu item was selected a 163 pointer to the menu item is returned, if not, \c NULL is returned. 164*/ 165 166 167/*! 168 \fn void BPopUpMenu::SetAsyncAutoDestruct(bool on) 169 \brief Indicates whether or not the BPopUpMenu will delete itself after 170 closing, async-auto-destruct mode is set to \c false by default. 171 172 \param on \c true to turn async-auto-destruct mode on, \c false to turn 173 async-auto-destruct mode off. 174*/ 175 176 177/*! 178 \fn bool BPopUpMenu::AsyncAutoDestruct() const 179 \brief Returns the current async-auto-destruct setting. 180 181 \return \c true if async-auto-destruct mode is turned on, \c false if 182 async-auto-destruct mode is turned off. 183 184 \see SetAsyncAutoDestruct() 185*/ 186 187 188/*! 189 \fn BPoint BPopUpMenu::ScreenLocation() 190 \brief Returns where the pop-up menu will appear on screen when it is 191 opened. 192 193 You can override this method in your BPopUpMenu derived class to return 194 where the pop-up menu will appear on screen. 195 196 \returns The location that the pop-up-menu will appear on screen in the 197 screen's coordinate system. 198*/ 199 200 201/*! 202 \fn BPopUpMenu& BPopUpMenu::operator=(const BPopUpMenu& other) 203 \brief Assignment overload method. 204 205 \param other The BPopUpMenu object to assign from. 206 207 \return The newly assigned BPopUpMenu object. 208*/ 209