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 If this item is attached to a menu, it will be removed from it. 119 120 Also destroys the label and submenu. 121 122 \since BeOS R3 123*/ 124 125 126/*! 127 \name Archiving 128*/ 129 130 131//! @{ 132 133 134/*! 135 \fn BArchivable* BMenuItem::Instantiate(BMessage* data) 136 \brief Creates a new BMenuItem object from an \a data message. 137 138 \return A newly created BMenuItem object or \c NULL if the message 139 doesn't contain an archived BMenuItem. 140 141 \since BeOS R3 142*/ 143 144 145/*! 146 \fn status_t BMenuItem::Archive(BMessage* data, bool deep) const 147 \brief Archives the the BMenuItem object into the \a data message. 148 149 Adds the label and current state of the BMenuItem to the archive. 150 151 \param data A pointer to the BMessage to archive the object into. 152 \param deep Whether or not to archive attached menus as well. 153 154 \return A status code, \c B_OK if everything went well or an error code 155 otherwise. 156 \retval B_OK The object was archived successfully. 157 \retval B_NO_MEMORY Ran out of memory while archiving the object. 158 159 \since BeOS R3 160*/ 161 162 163//! @} 164 165 166/*! 167 \fn void BMenuItem::SetLabel(const char* string) 168 \brief Sets the menu item label to \a string. 169 170 The memory used by the label is copied so you may free the original. 171 Setting the label invalidates the attached menu. 172 173 \param string The \a string to set the label to. 174 175 \since BeOS R3 176*/ 177 178 179/*! 180 \fn void BMenuItem::SetEnabled(bool enable) 181 \brief Enables or disables the menu item. 182 183 Enabling or disabling the menu item invalidates the attached menu. 184 185 \param enable \c true to enable the menu item, \c false to disable it. 186 187 \since BeOS R3 188*/ 189 190 191/*! 192 \fn void BMenuItem::SetMarked(bool mark) 193 \brief Marks or unmarks the menu item. 194 195 Marking or unmarking the menu item invalidates the attached menu. 196 197 Marking a menu item attached to a menu in radio mode causes the currently 198 marked item to be unmarked. 199 200 \param mark \c true to mark the menu item, \c false to unmark it. 201 202 \sa BMenu::SetRadioMode() 203 204 \since BeOS R3 205*/ 206 207 208/*! 209 \fn void BMenuItem::SetTrigger(char trigger) 210 \brief Set the character that activates this menu item. The triggered 211 character is drawn underlined in the menu. 212 213 \attention Triggers are currently disabled. 214 215 \param trigger The trigger character to set on this menu item. 216 217 \since BeOS R3 218*/ 219 220 221/*! 222 \fn void BMenuItem::SetShortcut(char shortcut, uint32 modifiers) 223 \brief Set the keyboard shortcut of the menu item. 224 225 Setting a shortcut invalidates the attached menu. 226 227 This method will override the existing shortcut set to the window. 228 229 \param shortcut The ASCII shortcut character to set. 230 \param modifiers A bitmap mask of modifier keys used to activate 231 the shortcut. 232 233 \since BeOS R3 234*/ 235 236 237/*! 238 \fn const char* BMenuItem::Label() const 239 \brief Returns the item's label. 240 241 \return The item's label as a const char array. 242 243 \since BeOS R3 244*/ 245 246 247/*! 248 \fn bool BMenuItem::IsEnabled() const 249 \brief Returns whether or not the item is enabled. 250 251 \return \c true if the item is enabled, \c false if disabled. 252 253 \since BeOS R3 254*/ 255 256 257/*! 258 \fn bool BMenuItem::IsMarked() const 259 \brief Returns whether or not the item is marked. 260 261 \return \c true if the item is marked, \c false if unmarked. 262 263 \since BeOS R3 264*/ 265 266 267/*! 268 \fn char BMenuItem::Trigger() const 269 \brief Returns the item's trigger character. 270 271 \return The current trigger character as a char or 0 if unset. 272 273 \since BeOS R3 274*/ 275 276 277/*! 278 \fn char BMenuItem::Shortcut(uint32* modifiers) const 279 \brief Returns the currently set shortcut and fills out \a modifiers 280 with a bitmap of the modifier keys required to invoke the item. 281 282 \param modifiers A pointer to a uint32 to fill out. 283 284 \return The shortcut character assigned to the menu item as a char. 285 286 \since BeOS R3 287*/ 288 289 290/*! 291 \fn BMenu* BMenuItem::Submenu() const 292 \brief Returns a pointer to the attached menu. 293 294 \return A pointer to the attached menu. 295 296 \since BeOS R3 297*/ 298 299 300/*! 301 \fn BMenu* BMenuItem::Menu() const 302 \brief Returns a pointer to the menu that the item is attached to. 303 304 \return A pointer to the menu that the item is attached to. 305 306 \since BeOS R3 307*/ 308 309 310/*! 311 \fn BRect BMenuItem::Frame() const 312 \brief Returns the bounds rectangle of the menu item. 313 314 \return The bounds rectangle of the menu item in the coordinate system 315 of the menu that the item is attached to. 316 317 \since BeOS R3 318*/ 319 320 321/*! 322 \fn void BMenuItem::GetContentSize(float* _width, float* _height) 323 \brief Fills out \a _width and \a _height with the content rectangle 324 dimensions. 325 326 You only need to call this method if you're implementing your own 327 DrawContent() method to override how the contents of the menu item 328 are drawn. 329 330 The content rectangle excludes the item margins and the area that 331 contains the checkmark, shortcut, and submenu arrow. 332 333 The content rectangle can be calculated using this method as well as 334 ContentLocation() to get location of the top left corner. 335 336 \param _width Filled out with the width of the content rectangle. 337 \param _height Filled out with the height of the content rectangle. 338 339 \sa ContentLocation() 340 \sa DrawContent() 341 342 \since BeOS R3 343*/ 344 345 346/*! 347 \fn void BMenuItem::TruncateLabel(float maxWidth, char* newLabel) 348 \brief Truncates the label and stashes it into \a newLabel. 349 350 You are responsible for allocating \a newLabel with enough space to fit 351 the label including the trailing \c NUL. The method will \c NUL terminate 352 the string for you. 353 354 \param maxWidth The maximum number of bytes to truncate the label to. 355 \param newLabel The buffer to store the truncated label in. 356 357 \since BeOS R3 358*/ 359 360 361/*! 362 \fn void BMenuItem::DrawContent() 363 \brief Hook method used to draw the menu items contents. 364 365 This method is called automatically by BMenu::Draw(), you need not call it 366 yourself. You may want to override this method in derived classes to do 367 something different than drawing a text label. 368 369 \since BeOS R3 370*/ 371 372 373/*! 374 \fn void BMenuItem::Draw() 375 \brief Hook method used to draw the menu items. 376 377 This method is called by automatically by BMenu::Draw(). You should not need to 378 call this method yourself but you may want to override it in a derived class 379 to do something other than the default. The default draws the mark, shortcut 380 and possibly a right arrow to indicate there is submenu and then calls 381 DrawContent() to fill in the label. Lastly Highlight() is called if the item 382 is selected. 383 384 \since BeOS R3 385*/ 386 387 388/*! 389 \fn void BMenuItem::Highlight(bool highlight) 390 \brief Highlights or unhighlights the menu item. 391 392 This method is called by Draw() when the item is selected or unselected. 393 394 You shouldn't need to call this method unless you override the Draw() 395 method in a derived class and you want to highlight differently. 396 397 \param highlight Highlights if \a highlight is \c true, 398 unhighlights if \c false. 399 400 \since BeOS R3 401*/ 402 403 404/*! 405 \fn bool BMenuItem::IsSelected() const 406 \brief Returns whether or not the item is selected. 407 408 \return \c true if selected, \c false if not selected. 409 410 \since BeOS R3 411*/ 412 413 414/*! 415 \fn BPoint BMenuItem::ContentLocation() const 416 \brief Returns the top-left point of the content rectangle. 417 418 You only need to call this method if you're implementing your own 419 DrawContent() method to override how the contents of the menu item 420 are drawn. 421 422 The content rectangle can be calculated using this method as well as 423 GetContentSize() to get the width and height. 424 425 \return The top-left point of the content rectangle as a BPoint in the 426 coordinate system of the attached BMenu. 427 428 \sa GetContentSize() 429 \sa DrawContent() 430 431 \since BeOS R3 432*/ 433 434 435/*! 436 \fn status_t BMenuItem::Invoke(BMessage* message) 437 \brief Sends a copy of the model \a message to the target. 438 439 This method extends BInvoker::Invoke() to guarantee that only enabled items 440 attached to the menu can be invoked and automatically marks the item. 441 442 The following fields added to the \a message: 443 - "when" \c B_INT64_TYPE system_time() 444 - "source" \c B_POINTER_TYPE A pointer to the menu item object. 445 - "index" \c B_INT32_TYPE The index of the menu item. 446 447 \param message The message to send or \c NULL to send the message set in 448 the constructor. 449 450 \return \c B_OK on success or an error code on error. 451 \retval B_OK The message was sent successfully. 452 \retval B_BAD_VALUE The message was \c NULL. 453 454 \sa BInvoker::Invoke() 455 456 \since BeOS R3 457*/ 458