/usr/include/Wt/WMenu is in libwt-dev 3.3.6+dfsg-1.1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 | // This may look like C code, but it's really -*- C++ -*-
/*
* Copyright (C) 2008 Emweb bvba, Kessel-Lo, Belgium.
*
* See the LICENSE file for terms of use.
*/
#ifndef WMENU_H_
#define WMENU_H_
#include <vector>
#include <Wt/WCompositeWidget>
#include <Wt/WMenuItem>
namespace Wt {
/*! \class WMenu Wt/WMenu Wt/WMenu
* \brief A widget that shows a menu of options.
*
* The %WMenu widget offers menu navigation.
*
* Typically, a menu is used in conjunction with a WStackedWidget (but
* can be used without too), where different 'contents' are stacked
* upon each other. Each choice in the menu (which is implemented as a
* WMenuItem) corresponds to a tab in the contents stack. The contents
* stack may contain other items, and could be shared with other WMenu
* instances.
*
* When used without a contents stack, you can react to menu item
* selection using the itemSelected() signal, to implement some custom
* handling of item selection.
*
* Usage example:
* \if cpp
* \code
* // create the stack where the contents will be located
* Wt::WStackedWidget *contents = new Wt::WStackedWidget(contentsParent);
*
* // create a menu
* Wt::WMenu *menu = new Wt::WMenu(contents, menuParent);
*
* // add four items using the default lazy loading policy.
* menu->addItem("Introduction", new Wt::WText("intro"));
* menu->addItem("Download", new Wt::WText("Not yet available"));
* menu->addItem("Demo", new DemoWidget());
* menu->addItem(new Wt::WMenuItem("Demo2", new DemoWidget()));
* \endcode
* \elseif java
* \code
* // create the stack where the contents will be located
* WStackedWidget contents = new WStackedWidget(contentsParent);
*
* // create a menu
* WMenu menu = new WMenu(contents, menuParent);
*
* // add four items using the default lazy loading policy.
* menu.addItem("Introduction", new WText("intro"));
* menu.addItem("Download", new WText("Not yet available"));
* menu.addItem("Demo", new DemoWidget());
* menu.addItem(new WMenuItem("Demo2", new DemoWidget()));
* \endcode
* \endif
*
* After contruction, the first entry will be selected. At any time,
* it is possible to select a particular item using select().
*
* Each item of %WMenu may be closeable (see WMenuItem::setCloseable(bool).
* Like selection, at any time, it is possible to close a particular item
* using close(). You can react to close of item by using the itemClosed()
* signal.
*
* The %WMenu implementation offers fine-grained control on how
* contents should be preloaded. By default, all contents is
* lazy-loaded, only when needed. To improve response time, an item
* may also be preloaded (using addItem()). In that case, the item
* will be loaded in the background, before its first use. In any
* case, once the contents corresponding to a menu item is loaded,
* subsequent navigation to it is handled entirely client-side.
*
* The %WMenu may participate in the application's internal path,
* which lets menu items correspond to internal URLs, see
* setInternalPathEnabled().
*
* The layout of the menu may be Horizontal or Vertical. The look of
* the items may be defined through style sheets. The default
* WMenuItem implementation uses four style classes to distinguish
* between inactivated, activated, closeable inactivated and closeable
* activated menu items: <tt>"item"</tt>, <tt>"itemselected"</tt>,
* <tt>"citem"</tt>, <tt>"citemselected"</tt>. By using CSS nested selectors,
* a different style may be defined for items in a different menu.
*
* You may customize the rendering and behaviour of menu entries by
* specializing WMenuItem.
*
* <h3>CSS</h3>
*
* The menu is rendered as a >ul<. Unless you use the bootstrap
* theme, you will want to customize the menu using inline or external
* styles to hide the bullets and provide the appropriate horizontal
* or vertical layout.
*
* \sa WMenuItem
*/
class WT_API WMenu : public WCompositeWidget
{
public:
/*! \brief Creates a new menu (<b>deprecated</b>).
*
* Construct a menu with given \p orientation. The menu is not
* associated with a contents stack, and thus you will want to react
* to the itemSelected() signal to react to menu changes.
*
* \deprecated the \p orientation parameter is ignored, since menus
* are now always rendered using <ul> elements,
* and CSS will determine the orientation.
* Use WMenu(WContainerWidget *) instead.
*/
WMenu(Orientation orientation, WContainerWidget *parent = 0);
/*! \brief Creates a new menu.
*
* The menu is not associated with a contents stack, and thus you
* will want to react to the itemSelected() signal to react to menu
* changes.
*/
WMenu(WContainerWidget *parent = 0);
/*! \brief Creates a new menu (<b>deprecated</b>).
*
* Construct a menu to manage the widgets in \p contentsStack,
* and sets the menu \p orientation.
*
* Each menu item will manage a single widget in the
* \p contentsStack, making it the current widget when the menu
* item is activated.
*
* \deprecated the \p orientation parameter is ignored, since menus
* are now always rendered using <ul> elements,
* and CSS will determine the orientation.
* Use WMenu(WStackedWidget *contentsStack, WContainerWidget *)
* instead.
*/
WMenu(WStackedWidget *contentsStack, Orientation orientation,
WContainerWidget *parent = 0);
/*! \brief Creates a new menu.
*
* Construct a menu to manage the widgets in \p contentsStack.
*
* Each menu item will manage a single widget in the
* \p contentsStack, making it the current widget when the menu
* item is activated.
*/
WMenu(WStackedWidget *contentsStack, WContainerWidget *parent = 0);
/*! \brief Destructor.
*/
~WMenu();
/*! \brief Adds an item.
*
* Use this version of addItem() if you do not want to specify an icon
* for this menu item.
*
* Returns the corresponding WMenuItem.
*
* \sa addItem(const std::string&, const WString&, WWidget *, WMenuItem::LoadPolicy)
* \sa addItem(WMenuItem *)
*/
WMenuItem *addItem(const WString& label, WWidget *contents = 0,
WMenuItem::LoadPolicy policy = WMenuItem::LazyLoading);
/*! \brief Adds an item.
*
* Adds a menu item with given \p contents, which is added to the
* menu's associated contents stack.
*
* \p contents may be \c 0 for two reasons:
* - if the menu is not associated with a contents stack, then you cannot
* associate a menu item with a contents widget
* - or, you may have one or more items which which are not associated with
* a contents widget in the contents stack.
*
* Returns the corresponding WMenuItem.
*
* \sa addItem(WMenuItem *)
*/
WMenuItem *addItem(const std::string& iconPath, const WString& label,
WWidget *contents = 0,
WMenuItem::LoadPolicy policy = WMenuItem::LazyLoading);
/*! \brief Adds an item with given text, and specify a slot method to be
* called when the item is triggered.
*
* The <i>target</i> and \p method are connected to the
* WMenuItem::triggered signal.
*
* \sa add(WMenuItem *)
*/
template<class T, class V>
WMenuItem *addItem(const WString& text, T *target, void (V::*method)());
/*! \brief Adds an item with given text and icon, and specify a slot
* method to be called when activated.
*
* The <i>target</i> and \p method are connected to the
* WMenuItem::triggered signal.
*
* \note The icon should have a width of 16 pixels.
*
* \sa add(WMenuItem *)
*/
template<class T, class V>
WMenuItem *addItem(const std::string& iconPath, const WString& text,
T *target, void (V::*method)());
/*! \brief Adds a submenu, with given text.
*
* Adds an item with text \p text, that leads to a submenu
* \p menu.
*
* \sa add(WMenuItem *)
*/
WMenuItem *addMenu(const WString& text, WMenu *menu);
/*! \brief Adds a submenu, with given icon and text.
*
* Adds an item with given text and icon, that leads to a submenu
* \p menu.
*
* \sa add(WMenuItem *)
*/
WMenuItem *addMenu(const std::string& iconPath, const WString& text,
WMenu *menu);
/*! \brief Adds an item.
*
* Adds a menu item. Use this form to add specialized WMenuItem
* implementations.
*
* \sa addItem(const WString&, WWidget *, WMenuItem::LoadPolicy)
*/
virtual void addItem(WMenuItem *item);
/*! \brief inserts an item.
*
* Use this version of insertItem() if you do not want to specify an icon
* for this menu item.
*
* Returns the corresponding WMenuItem.
*
* \sa insertItem(int index, const std::string&, const WString&, WWidget *, WMenuItem::LoadPolicy)
* \sa insertItem(int index, WMenuItem *)
*/
WMenuItem *insertItem(int index, const WString& label, WWidget *contents = 0,
WMenuItem::LoadPolicy policy = WMenuItem::LazyLoading);
/*! \brief inserts an item.
*
* inserts a menu item with given \p contents, which is inserted to the
* menu's associated contents stack.
*
* \p contents may be \c 0 for two reasons:
* - if the menu is not associated with a contents stack, then you cannot
* associate a menu item with a contents widget
* - or, you may have one or more items which which are not associated with
* a contents widget in the contents stack.
*
* Returns the corresponding WMenuItem.
*
* \sa insertItem(int index, WMenuItem *)
*/
WMenuItem *insertItem(int index, const std::string& iconPath,
const WString& label, WWidget *contents = 0,
WMenuItem::LoadPolicy policy = WMenuItem::LazyLoading);
/*! \brief inserts an item with given text, and specify a slot method to be
* called when the item is triggered.
*
* The <i>target</i> and \p method are connected to the
* WMenuItem::triggered signal.
*
* \sa insert(int index,WMenuItem *)
*/
template<class T, class V>
WMenuItem *insertItem(int index, const WString& text,
T *target, void (V::*method)());
/*! \brief inserts an item with given text and icon, and specify a slot
* method to be called when activated.
*
* The <i>target</i> and \p method are connected to the
* WMenuItem::triggered signal.
*
* \note The icon should have a width of 16 pixels.
*
* \sa insert(int index, WMenuItem *)
*/
template<class T, class V>
WMenuItem *insertItem(int index, const std::string& iconPath,
const WString& text, T *target, void (V::*method)());
/*! \brief inserts a submenu, with given text.
*
* inserts an item with text \p text, that leads to a submenu
* \p menu.
*
* \sa insert(int index, WMenuItem *)
*/
WMenuItem *insertMenu(int index, const WString& text, WMenu *menu);
/*! \brief inserts a submenu, with given icon and text.
*
* inserts an item with given text and icon, that leads to a submenu
* \p menu.
*
* \sa insert(int index, WMenuItem *)
*/
WMenuItem *insertMenu(int index, const std::string& iconPath,
const WString& text, WMenu *menu);
/*! \brief Inserts an item.
*
* Inserts a menu item. Use this form to insert specialized WMenuItem
* implementations.
*
* \sa insertItem(WMenuItem *item)
*/
virtual void insertItem(int index, WMenuItem *item);
/*! \brief Adds a separator to the menu.
*
* Adds a separator the menu.
*/
WMenuItem *addSeparator();
/*! \brief Adds a section header to the menu.
*/
WMenuItem *addSectionHeader(const WString& text);
/*! \brief Removes an item.
*
* Removes the given item. The item and its contents is not deleted.
*
* \sa addItem()
*/
virtual void removeItem(WMenuItem *item);
/*! \brief Selects an item.
*
* Select the menu item \p item.
*
* When \p item is \c 0, the current selection is removed.
*
* \sa select(int), currentItem(), WMenuItem::select()
*/
void select(WMenuItem *item);
/*! \brief Selects an item.
*
* Menu items in a menu with \p N items are numbered from 0 to
* \p N - 1.
*
* Using a value of -1 removes the current selection.
*
* \sa select(WMenuItem *), currentIndex()
*/
void select(int index);
/*! \brief %Signal which indicates that a new item was selected.
*
* This signal is emitted when an item was selected. It is emitted
* both when the user activated an item, or when select() was
* invoked.
*
* \sa itemSelectRendered()
*/
Signal<WMenuItem *>& itemSelected() { return itemSelected_; }
/*! \brief %Signal which indicates that a new selected item is rendered.
*
* This signal is similar to \link WMenu::itemSelected
* itemSelected\endlink, but is emitted from within a stateless
* slot. Therefore, any slot connected to this signal will be
* optimized to client-side JavaScript, and must support the
* contract of a stateless slot (i.e., be idempotent).
*
* If you are unsure what is the difference with the \link
* WMenu::itemSelected itemSelected\endlink signal, you'll probably
* need the latter instead.
*
* \sa itemSelected()
*/
Signal<WMenuItem *>& itemSelectRendered() { return itemSelectRendered_; }
/*! \brief Closes an item.
*
* Close the menu item \p item. Only \link WMenuItem::setCloseable(bool)
* closeable\endlink items can be closed.
*
* \sa close(int), WMenuItem::close()
*/
void close(WMenuItem *item);
/*! \brief Closes an item.
*
* Menu items in a menu with \p N items are numbered from 0 to
* \p N - 1.
*
* \sa close(WMenuItem *)
*/
void close(int index);
/*! \brief Returns the items.
*
* Returns the list of menu items in this menu.
*
* \sa itemAt()
*/
std::vector<WMenuItem *> items() const;
/*! \brief %Signal which indicates that an item was closed.
*
* This signal is emitted when an item was closed. It is emitted
* both when the user closes an item, or when close() was
* invoked.
*/
Signal<WMenuItem *>& itemClosed() { return itemClosed_; }
/*! \brief Hides an item.
*
* Hides the menu item \p item. By default, all menu items are
* visible.
*
* If the item was currently selected, then the next item to be selected
* is determined by nextAfterHide().
*
* \sa setItemHidden(int, bool), WMenuItem::hide()
*/
void setItemHidden(WMenuItem *item, bool hidden);
/*! \brief Hides an item.
*
* Menu items in a menu with \p N items are numbered from 0 to \p N - 1.
*
* \sa setItemHidden(WMenuItem *, bool)
*/
void setItemHidden(int index, bool hidden);
/*! \brief Returns whether the item widget of the given item is hidden.
*
* \sa setItemHidden()
*/
bool isItemHidden(WMenuItem *item) const;
/*! \brief Returns whether the item widget of the given index is hidden.
*
* Menu items in a menu with \p N items are numbered from 0 to \p N - 1.
*
* \sa setItemHidden()
*/
bool isItemHidden(int index) const;
/*! \brief Disables an item.
*
* Disables the menu item \p item. Only an item that is enabled can
* be selected. By default, all menu items are enabled.
*
* \sa setItemDisabled(int, bool), WMenuItem::setDisabled()
*/
void setItemDisabled(WMenuItem *item, bool disabled);
/*! \brief Disables an item.
*
* Menu items in a menu with \p N items are numbered from 0 to
* \p N - 1.
*
* \sa setItemDisabled(WMenuItem *, bool)
*/
void setItemDisabled(int index, bool disabled);
/*! \brief Returns whether the item widget of the given item is disabled.
*
* \sa setItemDisabled()
*/
bool isItemDisabled(WMenuItem *item) const;
/*! \brief Returns whether the item widget of the given index is disabled.
*
* Menu items in a menu with \p N items are numbered from 0 to
* \p N - 1.
*
* \sa setItemDisabled()
*/
bool isItemDisabled(int index) const;
/*! \brief Returns the currently selected item.
*
* \sa currentIndex(), select(WMenuItem *)
*/
WMenuItem *currentItem() const;
/*! \brief Returns the index of the currently selected item.
*
* \sa currentItem(), select(int)
*/
int currentIndex() const { return current_; }
/*! \brief Returns the orientation (<b>deprecated</b>).
*
* The orientation is set at time of construction.
*
* \deprecated this function no longer has any use and will be removed.
*/
Orientation orientation() const { return Horizontal; }
/*! \brief Renders using an HTML list (<b>deprecated</b>)
*
* This function no longer has an effect, as a menu is now always rendered
* as a list.
*
* \deprecated this function no longer has any use and will be removed.
*/
void setRenderAsList(bool enable);
/*! \brief Returns whether the menu is rendered as an HTML list
* (<b>deprecated</b>).
*
* \deprecated this function no longer has any use and will be removed.
*/
bool renderAsList() const { return true; }
/*! \brief Enables internal paths for items.
*
* The menu participates in the internal path by changing the
* internal path when an item has been selected, and listening for
* path changes to react to path selections. As a consequence this
* allows the user to bookmark the current menu selection and
* revisit it later, use back/forward buttons to navigate through
* history of visited menu items, and allows indexing of pages.
*
* For each menu item, WMenuItem::pathComponent() is appended to the
* \p basePath, which defaults to the internal path
* (WApplication::internalPath()). A '/' is appended to the base
* path, to turn it into a folder, if needed.
*
* By default, menu interaction does not change the application
* internal path.
*
* \sa WMenuItem::setPathComponent().
*/
void setInternalPathEnabled(const std::string& basePath = "");
/*! \brief Returns whether the menu generates internal paths entries.
*
* \sa setInternalPathEnabled()
*/
bool internalPathEnabled() const { return internalPathEnabled_; }
/*! \brief Sets the internal base path.
*
* A '/' is appended to turn it into a folder, if needed.
*
* \sa setInternalPathEnabled(), internalBasePath()
*/
void setInternalBasePath(const std::string& basePath);
/*! \brief Returns the internal base path.
*
* The default value is the application's internalPath
* (WApplication::internalPath()) that was recorded when
* setInternalPathEnabled() was called, and together with each
* WMenuItem::pathComponent() determines the paths for each item.
*
* For example, if internalBasePath() is <tt>"/examples/"</tt> and
* pathComponent() for a particular item is <tt>"charts/"</tt>, then
* the internal path for that item will be
* <tt>"/examples/charts/"</tt>.
*
* \sa setInternalPathEnabled()
*/
const std::string& internalBasePath() const { return basePath_; }
/*! \brief Returns the contents stack associated with the menu.
*/
WStackedWidget *contentsStack() const { return contentsStack_; }
/*! \brief Returns the item count.
*/
int count() const;
/*! \brief Returns the item by index.
*
* \sa indexOf()
*/
WMenuItem *itemAt(int index) const;
/*! \brief Returns the index of an item.
*
* \sa itemAt()
*/
int indexOf(WMenuItem *item) const;
/*! \brief Returns the parent item (for a submenu)
*
* This is the item with which this menu is associated as a submenu
* (if any).
*/
WMenuItem *parentItem() const { return parentItem_; }
virtual void load();
protected:
virtual void render(WFlags<RenderFlag> flags);
/*! \brief Handling of internal path changes.
*
* This methods makes the menu react to internal path changes (and also
* the initial internal path).
*
* You may want to reimplement this if you want to customize the internal
* path handling.
*/
virtual void internalPathChanged(const std::string& path);
/*! \brief Returns the index of the item to be selected after hides.
*
* Returns the index of the item to be selected after the item with given
* index will be hidden.
*
* By default, if the given index is an index of currently selected item,
* returns an index of the first visible item to the right of it. If it is not
* found, returns the index of the first visible item to the left of it. If
* there are no visible items around the currently selected item, returns the
* index of currently selected item.
*
* You may want to reimplement this if you want to customize the algorithm
* of determining the index of the item to be selected after hiding the item
* with given index.
*/
virtual int nextAfterHide(int index);
protected:
WContainerWidget *ul() const { return ul_; }
virtual void renderSelected(WMenuItem *item, bool selected);
virtual void setCurrent(int index);
/*! \brief Selects an item.
*
* This is the internal function that implements the selection
* logic, including optional internal path change (if \p changePath
* is \c true). The latter may be \c false in case an internal path
* change itself is the reason for selection.
*/
virtual void select(int index, bool changePath);
private:
WContainerWidget *ul_;
WStackedWidget *contentsStack_;
bool internalPathEnabled_, emitPathChange_;
std::string basePath_, previousInternalPath_;
WMenuItem *parentItem_;
Signal<WMenuItem *> itemSelected_, itemSelectRendered_;
Signal<WMenuItem *> itemClosed_;
Wt::Signals::connection contentsStackConnection_;
void contentsDestroyed();
void handleInternalPathChange(const std::string& path);
int current_;
int previousStackIndex_;
bool needSelectionEventUpdate_;
void init();
void updateItemsInternalPath();
void itemPathChanged(WMenuItem *item);
void selectVisual(WMenuItem *item);
void undoSelectVisual();
void selectVisual(int item, bool changePath, bool showContents);
void onItemHidden(int index, bool hidden);
friend class WMenuItem;
void updateSelectionEvent();
};
template<class T, class V>
WMenuItem *WMenu::addItem(const WString& text, T *target, void (V::*method)())
{
return addItem(std::string(), text, target, method);
}
template<class T, class V>
WMenuItem *WMenu::addItem(const std::string& iconPath, const WString& text,
T *target, void (V::*method)())
{
WMenuItem *item = addItem(iconPath, text);
item->triggered().connect(target, method);
return item;
}
template<class T, class V>
WMenuItem *WMenu::insertItem(int index, const WString& text, T *target,
void (V::*method)())
{
return insertItem( index, std::string(), text, target, method);
}
template<class T, class V>
WMenuItem *WMenu::insertItem(int index, const std::string& iconPath,
const WString& text, T *target,
void (V::*method)())
{
WMenuItem *item = insertItem(index, iconPath, text);
item->triggered().connect(target, method);
return item;
}
}
#endif // WMENU_H_
|