docs/user/interface/PopUpMenu.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/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 */