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