docs/user/interface/MenuItem.dox

   1 /*
   2  * Copyright 2014 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/MenuItem.h  hrev46969
  10  *              src/kits/interface/MenuItem.cpp  hrev46969
  11  */
  12
  13
  14 /*!
  15         \file MenuItem.h
  16         \ingroup interface
  17         \ingroup libbe
  18         \brief BMenuItem class definition.
  19 */
  20
  21
  22 /*!
  23         \class BMenuItem
  24         \ingroup interface
  25         \ingroup libbe
  26         \brief Display item for the BMenu class.
  27
  28         A BMenuItem either consists of a label or a submenu and message that
  29         is sent to the attached menu's target when the item is selected. BMenu
  30         and BMenuItem work in concert with each other in order to create a
  31         menu tree hierarchy. BMenuItem's serve as nodes in the tree while
  32         BMenu's serve as branches.
  33
  34         \sa SetLabel()
  35
  36         A menu item, unless it represents a submenu, can have a keyboard
  37         shortcut which is a printable character used in combination with
  38         the \key{Command} key and possibly other modifiers to invoke the item.
  39         The shortcut is displayed right of the item's label.
  40
  41         \sa SetShortcut()
  42
  43         A menu item may also have a trigger character assigned to it that
  44         invokes the item without using the \key{Command} key. The trigger
  45         characters is drawn underlined in the menu item's label. Unlike
  46         shortcuts, triggers are automatically assigned to a menu item. You
  47         can set the trigger character explicitly by calling SetTrigger().
  48
  49         \sa SetTrigger()
  50
  51         \attention Triggers are currently disabled.
  52
  53         Both the shortcut character and trigger character are case-insensitive.
  54
  55         A menu item may be marked, which draws a checkmark on the left side
  56         of the item. only one menu items may
  57         be marked at a time if attached to a menu in radio mode.
  58
  59         \sa SetMarked()
  60         \sa BMenu::SetRadioMode()
  61
  62         Menu items can also be enabled or disabled. A disabled item's label is drawn
  63         in a lighter color to indicate that it may not be used. A disabled menu
  64         item may not be selected or invoked. If the menu item controls a submenu the
  65         submenu may still be opened but each of the items will be disabled.
  66
  67         \sa SetEnabled()
  68
  69         \since BeOS R3
  70 */
  71
  72
  73 /*!
  74         \fn BMenuItem::BMenuItem(const char* label, BMessage* message,
  75                 char shortcut, uint32 modifiers)
  76         \brief Creates a new BMenuItem object with the specified \a label
  77                and \a message.
  78
  79         \param label The text \a label that is displayed.
  80         \param message The BMessage that is sent when the item is selected.
  81         \param shortcut The \a shortcut characters to activate the menu item.
  82         \param modifiers The modifier keys to active the menu item,
  83                \c B_COMMAND_KEY is assumed.
  84
  85         \since BeOS R3
  86 */
  87
  88
  89 /*!
  90         \fn BMenuItem::BMenuItem(BMenu* menu, BMessage* message)
  91         \brief Creates a new BMenuItem object with the specified \a menu
  92                and \a message.
  93
  94         The menu item's label is derived from the \a menu name. This method
  95         makes the menu item a submenu.
  96
  97         \param menu The \a menu to assign to the item.
  98         \param message The BMessage that is sent when the item is selected.
  99
 100         \since BeOS R3
 101 */
 102
 103
 104 /*!
 105         \fn BMenuItem::BMenuItem(BMessage* data)
 106         \brief Archive constructor.
 107
 108         \param data The message \a data to construct the menu item from.
 109
 110         \since BeOS R3
 111 */
 112
 113
 114 /*!
 115         \fn BMenuItem::~BMenuItem()
 116         \brief Destructor.
 117
 118         Also frees the memory used by the label or submenu.
 119
 120         \since BeOS R3
 121 */
 122
 123
 124 /*!
 125         \name Archiving
 126 */
 127
 128
 129 //! @{
 130
 131
 132 /*!
 133         \fn BArchivable* BMenuItem::Instantiate(BMessage* data)
 134         \brief Creates a new BMenuItem object from an \a data message.
 135
 136         \return A newly created BMenuItem object or \c NULL if the message
 137                 doesn't contain an archived BMenuItem.
 138
 139         \since BeOS R3
 140 */
 141
 142
 143 /*!
 144         \fn status_t BMenuItem::Archive(BMessage* data, bool deep) const
 145         \brief Archives the the BMenuItem object into the \a data message.
 146
 147         Adds the label and current state of the BMenuItem to the archive.
 148
 149         \param data A pointer to the BMessage to archive the object into.
 150         \param deep Whether or not to archive attached menus as well.
 151
 152         \return A status code, \c B_OK if everything went well or an error code
 153                 otherwise.
 154         \retval B_OK The object was archived successfully.
 155         \retval B_NO_MEMORY Ran out of memory while archiving the object.
 156
 157         \since BeOS R3
 158 */
 159
 160
 161 //! @}
 162
 163
 164 /*!
 165         \fn void BMenuItem::SetLabel(const char* string)
 166         \brief Sets the menu item label to \a string.
 167
 168         The memory used by the label is copied so you may free the original.
 169         Setting the label invalidates the attached menu.
 170
 171         \param string The \a string to set the label to.
 172
 173         \since BeOS R3
 174 */
 175
 176
 177 /*!
 178         \fn void BMenuItem::SetEnabled(bool enable)
 179         \brief Enables or disables the menu item.
 180
 181         Enabling or disabling the menu item invalidates the attached menu.
 182
 183         \param enable \c true to enable the menu item, \c false to disable it.
 184
 185         \since BeOS R3
 186 */
 187
 188
 189 /*!
 190         \fn void BMenuItem::SetMarked(bool mark)
 191         \brief Marks or unmarks the menu item.
 192
 193         Marking or unmarking the menu item invalidates the attached menu.
 194
 195         Marking a menu item attached to a menu in radio mode causes the currently
 196         marked item to be unmarked.
 197
 198         \param mark \c true to mark the menu item, \c false to unmark it.
 199
 200         \sa BMenu::SetRadioMode()
 201
 202         \since BeOS R3
 203 */
 204
 205
 206 /*!
 207         \fn void BMenuItem::SetTrigger(char trigger)
 208         \brief Set the character that activates this menu item. The triggered
 209                character is drawn underlined in the menu.
 210
 211         \attention Triggers are currently disabled.
 212
 213         \param trigger The trigger character to set on this menu item.
 214
 215         \since BeOS R3
 216 */
 217
 218
 219 /*!
 220         \fn void BMenuItem::SetShortcut(char shortcut, uint32 modifiers)
 221         \brief Set the keyboard shortcut of the menu item.
 222
 223         Setting a shortcut invalidates the attached menu.
 224
 225         This method will override the existing shortcut set to the window.
 226
 227         \param shortcut The ASCII shortcut character to set.
 228         \param modifiers A bitmap mask of modifier keys used to activate
 229                the shortcut.
 230
 231         \since BeOS R3
 232 */
 233
 234
 235 /*!
 236         \fn const char* BMenuItem::Label() const
 237         \brief Returns the item's label.
 238
 239         \return The item's label as a const char array.
 240
 241         \since BeOS R3
 242 */
 243
 244
 245 /*!
 246         \fn bool BMenuItem::IsEnabled() const
 247         \brief Returns whether or not the item is enabled.
 248
 249         \return \c true if the item is enabled, \c false if disabled.
 250
 251         \since BeOS R3
 252 */
 253
 254
 255 /*!
 256         \fn bool BMenuItem::IsMarked() const
 257         \brief Returns whether or not the item is marked.
 258
 259         \return \c true if the item is marked, \c false if unmarked.
 260
 261         \since BeOS R3
 262 */
 263
 264
 265 /*!
 266         \fn char BMenuItem::Trigger() const
 267         \brief Returns the item's trigger character.
 268
 269         \return The current trigger character as a char or 0 if unset.
 270
 271         \since BeOS R3
 272 */
 273
 274
 275 /*!
 276         \fn char BMenuItem::Shortcut(uint32* modifiers) const
 277         \brief Returns the currently set shortcut and fills out \a modifiers
 278                with a bitmap of the modifier keys required to invoke the item.
 279
 280         \param modifiers A pointer to a uint32 to fill out.
 281
 282         \return The shortcut character assigned to the menu item as a char.
 283
 284         \since BeOS R3
 285 */
 286
 287
 288 /*!
 289         \fn BMenu* BMenuItem::Submenu() const
 290         \brief Returns a pointer to the attached menu.
 291
 292         \return A pointer to the attached menu.
 293
 294         \since BeOS R3
 295 */
 296
 297
 298 /*!
 299         \fn BMenu* BMenuItem::Menu() const
 300         \brief Returns a pointer to the menu that the item is attached to.
 301
 302         \return A pointer to the menu that the item is attached to.
 303
 304         \since BeOS R3
 305 */
 306
 307
 308 /*!
 309         \fn BRect BMenuItem::Frame() const
 310         \brief Returns the bounds rectangle of the menu item.
 311
 312         \return The bounds rectangle of the menu item in the coordinate system
 313                 of the menu that the item is attached to.
 314
 315         \since BeOS R3
 316 */
 317
 318
 319 /*!
 320         \fn void BMenuItem::GetContentSize(float* _width, float* _height)
 321         \brief Fills out \a _width and \a _height with the content rectangle
 322                dimensions.
 323
 324         You only need to call this method if you're implementing your own
 325         DrawContent() method to override how the contents of the menu item
 326         are drawn.
 327
 328         The content rectangle excludes the item margins and the area that
 329         contains the checkmark, shortcut, and submenu arrow.
 330
 331         The content rectangle can be calculated using this method as well as
 332         ContentLocation() to get location of the top left corner.
 333
 334         \param _width Filled out with the width of the content rectangle.
 335         \param _height Filled out with the height of the content rectangle.
 336
 337         \sa ContentLocation()
 338         \sa DrawContent()
 339
 340         \since BeOS R3
 341 */
 342
 343
 344 /*!
 345         \fn void BMenuItem::TruncateLabel(float maxWidth, char* newLabel)
 346         \brief Truncates the label and stashes it into \a newLabel.
 347
 348         You are responsible for allocating \a newLabel with enough space to fit
 349         the label including the trailing \c NUL. The method will \c NUL terminate
 350         the string for you.
 351
 352         \param maxWidth The maximum number of bytes to truncate the label to.
 353         \param newLabel The buffer to store the truncated label in.
 354
 355         \since BeOS R3
 356 */
 357
 358
 359 /*!
 360         \fn void BMenuItem::DrawContent()
 361         \brief Hook method used to draw the menu items contents.
 362
 363         This method is called automatically by BMenu::Draw(), you need not call it
 364         yourself. You may want to override this method in derived classes to do
 365         something different than drawing a text label.
 366
 367         \since BeOS R3
 368 */
 369
 370
 371 /*!
 372         \fn void BMenuItem::Draw()
 373         \brief Hook method used to draw the menu items.
 374
 375         This method is called by automatically by BMenu::Draw(). You should not need to
 376         call this method yourself but you may want to override it in a derived class
 377         to do something other than the default. The default draws the mark, shortcut
 378         and possibly a right arrow to indicate there is submenu and then calls
 379         DrawContent() to fill in the label. Lastly Highlight() is called if the item
 380         is selected.
 381
 382         \since BeOS R3
 383 */
 384
 385
 386 /*!
 387         \fn void BMenuItem::Highlight(bool highlight)
 388         \brief Highlights or unhighlights the menu item.
 389
 390         This method is called by Draw() when the item is selected or unselected.
 391
 392         You shouldn't need to call this method unless you override the Draw()
 393         method in a derived class and you want to highlight differently.
 394
 395         \param highlight Highlights if \a highlight is \c true,
 396                unhighlights if \c false.
 397
 398         \since BeOS R3
 399 */
 400
 401
 402 /*!
 403         \fn bool BMenuItem::IsSelected() const
 404         \brief Returns whether or not the item is selected.
 405
 406         \return \c true if selected, \c false if not selected.
 407
 408         \since BeOS R3
 409 */
 410
 411
 412 /*!
 413         \fn BPoint BMenuItem::ContentLocation() const
 414         \brief Returns the top-left point of the content rectangle.
 415
 416         You only need to call this method if you're implementing your own
 417         DrawContent() method to override how the contents of the menu item
 418         are drawn.
 419
 420         The content rectangle can be calculated using this method as well as
 421         GetContentSize() to get the width and height.
 422
 423         \return The top-left point of the content rectangle as a BPoint in the
 424                  coordinate system of the attached BMenu.
 425
 426         \sa GetContentSize()
 427         \sa DrawContent()
 428
 429         \since BeOS R3
 430 */
 431
 432
 433 /*!
 434         \fn status_t BMenuItem::Invoke(BMessage* message)
 435         \brief Sends a copy of the model \a message to the target.
 436
 437         This method extends BInvoker::Invoke() to guarantee that only enabled items
 438         attached to the menu can be invoked and automatically marks the item.
 439
 440         The following fields added to the \a message:
 441                 - "when"        \c B_INT64_TYPE         system_time()
 442                 - "source"      \c B_POINTER_TYPE       A pointer to the menu item object.
 443                 - "index"       \c B_INT32_TYPE         The index of the menu item.
 444
 445         \param message The message to send or \c NULL to send the message set in
 446                the constructor.
 447
 448         \return \c B_OK on success or an error code on error.
 449         \retval B_OK The message was sent successfully.
 450         \retval B_BAD_VALUE The message was \c NULL.
 451
 452         \sa BInvoker::Invoke()
 453
 454         \since BeOS R3
 455 */