Wt::WMenu Class Reference

A widget that shows a menu of options. More...

#include <WMenu>

Inheritance diagram for Wt::WMenu:

Inheritance graph
[legend]

List of all members.

Public Member Functions

 WMenu (WStackedWidget *contentsStack, Orientation orientation, WContainerWidget *parent=0)
 Construct a new WMenu.
 ~WMenu ()
 Destructor.
WMenuItemaddItem (const WString &name, WWidget *contents, WMenuItem::LoadPolicy policy=WMenuItem::LazyLoading)
 Add a menu item.
WMenuItemaddItem (WMenuItem *item)
 Add a menu item.
void select (WMenuItem *item)
 Select the menu item.
void select (int index)
 Select the menu item with the given index number.
void enableBrowserHistory (const std::string &id)
 Make the menu react to browser history.
const std::string & browserHistoryId () const
 Get the browser history key for this menu.
const std::vector
< WMenuItem * > & 
items () const
 The menu items.
WMenuItemcurrentItem () const
 The currently selected item.
int currentIndex () const
 Get the index of the currently selected item.
Orientation orientation () const
 Get the orientation for this menu.
void setRenderAsList (bool enable)
 Render using an HTML list.
bool renderAsList () const
 Return whether the menu is rendered as an HTML list.

Public Attributes

Signal< WMenuItem * > itemSelected
 Signal emitted when a new item is selected.
Signal< WMenuItem * > itemSelectRendered
 Signal emitted when a new selected item is rendered.


Detailed Description

A widget that shows a menu of options.

The WMenu widget offers menu navigation in conjunction with a WStackedWidget, 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 is dedicated to the menu, and should not contain any other widgets than those that are added to it by the WMenu.

An example for using WMenu is:

   // create the stack where the contents will be located
   WStackedWidget *contents = new WStackedWidget(contentsParent);

   // create a menu
   WMenu *menu = new WMenu(contents, WMenu::Vertical, menuParent);

   // add four items using the default lazy loading policy.
   menu->addItem("Introduction", new WText(tr("intro"));
   menu->addItem("Download", new WText("Not yet available"));
   menu->addItem("Demo", new DemoWidget());
   menu->addItem(new WMenuItem("Demo2", new DemoWidget()));

After contruction, by default, the first entry will be selected. At any time, it is possible to select a particular item using the select() member.

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. Once loaded, the contents will be 'cached', and menu operation is also completely client-side.

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 two style classes to distinguish between activated and inactivated menu items: "item" and "itemselected". By using CSS nested selectors, a different style may be defined for items in a different menu.

For example, the Wt homepage uses the following CSS rules to style the two menu (which both are assigned the style class .menu):

.menu * .item {
  cursor: pointer; cursor: hand;
  color: blue;
  text-decoration: underline;
}

.menu * .itemselected {
  color: blue;
  text-decoration: underline;
  font-weight: bold;  
}

See also:
WMenuItem

Constructor & Destructor Documentation

Wt::WMenu::WMenu ( WStackedWidget contentsStack,
Orientation  orientation,
WContainerWidget parent = 0 
)

Construct a new WMenu.

Construct a menu to manage the widgets in the given contents stack, and with the given orientation.


Member Function Documentation

WMenuItem * Wt::WMenu::addItem ( const WString name,
WWidget contents,
WMenuItem::LoadPolicy  policy = WMenuItem::LazyLoading 
)

Add a menu item.

Adds a menu text item, associated with the contents.

Returns the corresponding WMenuItem.

See also:
addItem(WMenuItem *)

WMenuItem * Wt::WMenu::addItem ( WMenuItem item  ) 

Add a menu item.

Adds a menu item. Use this form to add specialized WMenuItem implementations (with a different look than the default text).

See also:
addItem(const WString&, WWidget *, WMenuItem::LoadPolicy)

void Wt::WMenu::select ( WMenuItem item  ) 

Select the menu item.

Select the given menu item.

See also:
select(int), currentItem()

void Wt::WMenu::select ( int  index  ) 

Select the menu item with the given index number.

Menu items in a menu with N items are indexed from 0 to N-1.

See also:
select(WMenuItem *), currentIndex()

void Wt::WMenu::enableBrowserHistory ( const std::string &  id  ) 

Make the menu react to browser history.

By reacting to browser history, the menu will set and read its state in user bookmarks, and will react to the user navigating through its history with the forward and backward buttons.

The id must be an application-wide unique id that identifies this menu, and will become part of the URL.

See also:
browserHistoryId()

const std::string& Wt::WMenu::browserHistoryId (  )  const [inline]

Get the browser history key for this menu.

Returns the browser history id that was previously set using enableBrowserHistory(), or an empty string otherwise.

See also:
enableBrowserHistory()

const std::vector<WMenuItem *>& Wt::WMenu::items (  )  const [inline]

The menu items.

Returns the list of menu items in this menu.

WMenuItem * Wt::WMenu::currentItem (  )  const

The currently selected item.

See also:
currentIndex(), select(WMenuItem *)

int Wt::WMenu::currentIndex (  )  const [inline]

Get the index of the currently selected item.

See also:
currentItem(), select(int)

Orientation Wt::WMenu::orientation (  )  const [inline]

Get the orientation for this menu.

The orientation must be set at time of construction.

void Wt::WMenu::setRenderAsList ( bool  enable  ) 

Render using an HTML list.

By default, the the menu is rendered using an HTML <table> element for layout. Setting this option enables rendering using <ul> and <il> elements, as is commonly done for CSS-based designs.

You cannot use this method after items have been added to the menu.

bool Wt::WMenu::renderAsList (  )  const [inline]

Return whether the menu is rendered as an HTML list.

See also:
setRenderAsList(bool)


Member Data Documentation

Signal<WMenuItem *> Wt::WMenu::itemSelected

Signal emitted when a new item is selected.

This signal is emitted when a new menu item is selected, either by the user or through a call to one of the select() methods.

See also:
itemSelectRendered

Signal<WMenuItem *> Wt::WMenu::itemSelectRendered

Signal emitted when a new selected item is rendered.

This signal is similar to itemSelected, 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.

If you are unsure what is the difference with the itemSelected signal, you'll probably need the latter instead.

See also:
itemSelected


The documentation for this class was generated from the following files:
Generated on Mon Apr 14 15:15:01 2008 for Wt by doxygen 1.5.3