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/MenuField.h hrev46323 10 * src/kits/interface/MenuField.cpp hrev46323 11 */ 12 13 14/*! 15 \file MenuField.h 16 \ingroup interface 17 \ingroup libbe 18 \brief BMenuField class definition and support structures. 19*/ 20 21 22/*! 23 \class BMenuField 24 \ingroup interface 25 \ingroup libbe 26 \brief A labeled pop-up menu. 27 28 A menu field consists of a label and a menu bar. The label, if used, is 29 located to the left of the menu bar. The frame rectangle is divided 30 in half by default. You can call SetDivider() to change the ratio used by 31 the label and menu bar. 32 33 \image html BMenuField_example.png 34 35 A fixed-size menu field's menu bar width and height are limited 36 by the bounds set by the divider position and \a frame rectangle. 37 38 A variable-size menu field's menu bar is only as wide as it needs to 39 be in order to fit the currently selected menu item, and its height 40 depends on the user's menu font size preference. The height of the 41 frame rectangle is ignored. 42 43 If a menu field's frame rectangle is less than 20 pixels wide, the width 44 is unbounded, the menu bar grows as wide as it needs to in order to fit 45 the currently selected item. If the frame rectangle is wider than 20 46 pixels then the divider position and the width of the frame rectangle set 47 the maximum menu bar width. 48 49 \remark Layout-enabled menu field's are always fixed-size, however, you can 50 make them act like variable-size menu fields by adding them to a 51 horizontal group followed by glue. 52 53 If you're using the menu field as part of a BLayout you can get better 54 control over the placement of the label and menu bar by splitting the 55 label and menu field into separate BLayoutItem objects using the 56 CreateLabelLayoutItem() and CreateMenuBarLayoutItem() methods. 57 58 You must pass a menu object into the constructor containing the choices 59 the user can select from. The menu is owned by the menu field and its 60 memory will be freed when the menu field is deleted. A BPopUpMenu is 61 typically used instead of a regular BMenu because it opens directly 62 underneath the mouse pointer and is set to radio mode and 63 label-from-marked mode by default, but, this is entirely up to you. 64 65 \since BeOS R3 66*/ 67 68 69/*! 70 \fn BMenuField::BMenuField(BRect frame, const char* name, const char* label, 71 BMenu* menu, uint32 resizingMode, uint32 flags) 72 \brief Creates a new variable-size BMenuField object. 73 74 \param frame The \a frame rectangle of the menu field including the label. 75 \param name The \a name of the menu field, internal only, can be \c NULL. 76 \param label The \a label shown to the user, can be blank. 77 \param menu The \a menu of choices shown to the user, typically a BPopUpMenu. 78 \param resizingMode Defines the menu field's behavior when its parent is 79 resized, see BView for details. 80 \param flags The view flags, see BView for details. 81 82 \since BeOS R3 83*/ 84 85 86/*! 87 \fn BMenuField::BMenuField(BRect frame, const char* name, const char* label, 88 BMenu* menu, bool fixedSize, uint32 resizingMode, uint32 flags) 89 \brief Creates a new BMenuField object. This constructor allows a you to 90 create either a fixed-size or variable-size menu field. 91 92 \param frame The \a frame rectangle of the menu field including the label. 93 \param name The \a name of the menu field, internal only, can be \c NULL. 94 \param label The \a label shown to the user, can be blank. 95 \param menu The \a menu of choices shown to the user, typically a BPopUpMenu. 96 \param fixedSize \c true for fixed-size, \c false for variable-size. 97 \param resizingMode Defines the menu field's behavior when its parent is 98 resized, see BView for details. 99 \param flags The view flags, see BView for details. 100 101 \since BeOS R3 102*/ 103 104 105/*! 106 \fn BMenuField::BMenuField(const char* name, const char* label, BMenu* menu, 107 uint32 flags) 108 \brief Creates a new BMenuField object suitable as part of a BLayout. 109 110 \param name The \a name of the menu field, internal only, can be \c NULL. 111 \param label The \a label shown to the user, can be blank. 112 \param menu The \a menu of choices shown to the user, typically a BPopUpMenu. 113 \param flags The view flags, see BView for details. 114 115 \since Haiku R1 116*/ 117 118 119/*! 120 \fn BMenuField::BMenuField(const char* label, BMenu* menu, uint32 flags) 121 \brief Creates a new BMenuField object suitable as part of a BLayout. 122 This constructor omits the internal name parameter. 123 124 \param label The \a label shown to the user, can be blank. 125 \param menu The \a menu of choices shown to the user, typically a BPopUpMenu. 126 \param flags The view flags, see BView for details. 127 128 \since Haiku R1 129*/ 130 131 132/*! 133 \fn BMenuField::BMenuField(BMessage* data) 134 \brief Archive constructor. 135 136 \param data The message \a data to construct the menu field from. 137 138 \since BeOS R3 139*/ 140 141 142/*! 143 \fn BMenuField::~BMenuField() 144 \brief Destructor. 145 146 Also frees the memory used by the label and menu. 147 148 \since BeOS R3 149*/ 150 151 152/*! 153 \name Archiving 154*/ 155 156 157//! @{ 158 159 160/*! 161 \fn BArchivable* BMenuField::Instantiate(BMessage* data) 162 \brief Creates a new BMenuField object from an \a data message. 163 164 \returns A newly created BMenuField object or \c NULL if the message 165 doesn't contain an archived BMenuField. 166 167 \since BeOS R3 168*/ 169 170 171/*! 172 \fn status_t BMenuField::Archive(BMessage* data, bool deep) const 173 \brief Archives the the BMenuField object into the \a data message. 174 175 Adds the label, divider, and current state of the BMenuField to the archive. 176 177 \param data A pointer to the BMessage to archive the object into. 178 \param deep Whether or not to archive attached menu and menu items as well. 179 180 \return A status code, \c B_OK if everything went well or an error code 181 otherwise. 182 \retval B_OK The object was archived successfully. 183 \retval B_NO_MEMORY Ran out of memory while archiving the object. 184 185 \since BeOS R3 186*/ 187 188 189//! @} 190 191 192/*! 193 \name Hook Methods 194*/ 195 196 197//! @{ 198 199 200/*! 201 \fn status_t BMenuField::AllArchived(BMessage* into) const 202 \brief Hook method called when all views have been archived. 203 204 Also archives the label and menu bar. 205 206 \param into Archived data message. 207 208 \since BeOS R3 209*/ 210 211 212/*! 213 \fn status_t BMenuField::AllUnarchived(const BMessage* from) 214 \brief Hook method called when all views have been unarchived. 215 216 Also unarchives the label and menu bar. 217 218 \param from Unarchived data message. 219 220 \since BeOS R3 221*/ 222 223 224/*! 225 \fn void BMenuField::AttachedToWindow() 226 \brief Hook method called when the menu field is attached to a window. 227 228 Adjusts the background color to match the background color of the parent 229 view and adjusts the height to be the attached menu bar which depends on 230 the user's current menu font setting. 231 232 \since BeOS R3 233*/ 234 235 236/*! 237 \fn void BMenuField::AllAttached() 238 \brief Similar to AttachedToWindow() but this method is triggered after 239 all child views have already been attached to a window. 240 241 If the attached menu bar is too narrow it is resized it to fit the menu 242 items. 243 244 \since BeOS R3 245*/ 246 247 248/*! 249 \fn void BMenuField::Draw(BRect updateRect) 250 \brief Draws the area of the menu field that intersects \a updateRect. 251 252 The menu field is drawn differently based on whether or not it is the 253 current focus view and whether or not it is enabled. 254 255 \param updateRect The rectangular area to be drawn. 256 257 \since BeOS R3 258*/ 259 260 261/*! 262 \fn void BMenuField::FrameResized(float newWidth, float newHeight) 263 \brief Hook method called when the menu bar is resized. 264 265 Adjusts the menu bar size and location. 266 267 \copydetails BView::FrameResized() 268*/ 269 270 271/*! 272 \fn void BMenuField::KeyDown(const char* bytes, int32 numBytes) 273 \brief Hook method called when a keyboard key is pressed. 274 275 Provides for keyboard navigation allowing users to open the menu by pressing 276 the space bar, right arrow, or down arrow. 277 278 \copydetails BView::KeyDown() 279*/ 280 281 282/*! 283 \fn void BMenuField::MouseDown(BPoint where) 284 \brief Hook method called when a mouse button is pressed. 285 286 Provides the ability to open the menu field menu using the mouse, even if 287 the user clicks on the menu field label. 288 289 \copydetails BView::MouseDown() 290*/ 291 292 293/*! 294 \fn void BMenuField::WindowActivated(bool active) 295 \brief Hook method called when the attached window is activated or 296 deactivated. 297 298 Redraws the focus ring around the menu field when the window is activated 299 and deactivated if it is the window's current focus view. 300 301 \copydetails BView::WindowActivated() 302*/ 303 304 305//! @} 306 307 308/*! 309 \fn void BMenuField::MakeFocus(bool focused) 310 \brief Makes the view the current focus view of the window or gives up 311 being the focus view of the window. 312 313 Enables or disables keyboard navigation and invalidates the menu field. 314 315 \param focused \a true to set focus, \a false to remove it. 316 317 \since BeOS R3 318*/ 319 320 321/*! 322 \fn BMenu* BMenuField::Menu() const 323 \brief Returns a pointer to the menu attached to the menu bar that opens 324 when the user clicks on the menu field. 325 326 \since BeOS R3 327*/ 328 329 330/*! 331 \fn BMenuBar* BMenuField::MenuBar() const 332 \brief Returns a pointer to the attached menu bar that contains the pop-up 333 menu. 334 335 \since BeOS R3 336*/ 337 338 339/*! 340 \fn BMenuItem* BMenuField::MenuItem() const 341 \brief Returns the first menu item attached to the menu bar containing 342 the pop-up menu. 343 344 \since BeOS R3 345*/ 346 347 348/*! 349 \fn void BMenuField::SetLabel(const char* label) 350 \brief Sets the menu field label to \a label. 351 352 \param label The \a label to set to the menu field. 353 354 \since BeOS R3 355*/ 356 357 358/*! 359 \fn const char* BMenuField::Label() const 360 \brief Returns the menu field label. 361 362 \return The menu field label or \c NULL if not assigned. 363 364 \since BeOS R3 365*/ 366 367 368/*! 369 \fn void BMenuField::SetEnabled(bool on) 370 \brief Enables or disables the menu field. 371 372 \param on \c true to enable the menu field, \c false to disable it. 373 374 \since BeOS R3 375*/ 376 377 378/*! 379 \fn bool BMenuField::IsEnabled() const 380 \brief Returns whether or not the menu is enabled. 381 382 \return \c true if the menu is enabled, \c false if disabled. 383 384 \since BeOS R3 385*/ 386 387 388/*! 389 \fn void BMenuField::SetAlignment(alignment label) 390 \brief Set the alignment of the menu field label. The default alignment 391 is \c B_ALIGN_LEFT. 392 393 \remark For menu fields that are part of a BLayout consider 394 using BLayoutItem::SetExplicitAlignment() instead. 395 396 \param label The alignment to set, choices include: 397 - \c B_ALIGN_LEFT 398 - \c B_ALIGN_CENTER 399 - \c B_ALIGN_RIGHT 400 401 \since BeOS R3 402*/ 403 404 405/*! 406 \fn alignment BMenuField::Alignment() const 407 \brief Returns the label's current alignment. 408 409 \return The label's current alignment constant. 410 411 \see SetAlignment() for more details. 412 413 \since BeOS R3 414*/ 415 416 417/*! 418 \fn void BMenuField::SetDivider(float position) 419 \brief Sets the horizontal \a position of the divider that separates the 420 label from the menu bar. 421 422 \remark It is not recommended to use this method for menu fields that are 423 part of a BLayout. Instead split the label and menu bar into 424 separate layout items using CreateLabelLayoutItem() and 425 CreateMenuBarLayoutItem(). This allows you to have better control 426 over the position of the label and menu bar portions of your 427 menu fields. 428 429 \param position The divider \a position to set, should be an integral value. 430 431 \since BeOS R3 432*/ 433 434 435/*! 436 \fn float BMenuField::Divider() const 437 \brief Returns the current divider position. 438 439 \return The current divider position as a float. 440 441 \see SetDivider() for more details. 442 443 \since BeOS R3 444*/ 445 446 447/*! 448 \fn void BMenuField::ShowPopUpMarker() 449 \brief Shows the pop-up marker located on the right edge of the menu bar. 450 451 \sa HidePopUpMarker() 452 453 \since Haiku R1 454*/ 455 456 457/*! 458 \fn void BMenuField::HidePopUpMarker() 459 \brief Hides to pop-up marker. 460 461 \sa ShowPopUpMarker() 462 463 \since Haiku R1 464*/ 465 466 467/*! 468 \fn BLayoutItem* BMenuField::CreateLabelLayoutItem() 469 \brief Returns a pointer to the label layout item. 470 (Layout constructor only) 471 472 \sa CreateMenuBarLayoutItem() 473 474 \since Haiku R1 475*/ 476 477 478/*! 479 \fn BLayoutItem* BMenuField::CreateMenuBarLayoutItem() 480 \brief Returns a pointer to the menu bar layout item. 481 (Layout constructor only) 482 483 \sa CreateLabelLayoutItem() 484 485 \since Haiku R1 486*/ 487
