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*/ 456