a list of items that specify options or group of options for an application. More...

Inheritance diagram for nana::menu:

Classes
struct	implement

Public Types
typedef drawerbase::menu::checks	checks

typedef drawerbase::menu::renderer_interface	renderer_interface

typedef drawerbase::menu::menu_item_type::item_proxy	item_proxy

typedef drawerbase::menu::menu_item_type::event_fn_t	event_fn_t
	A callback functor type. Prototype: `void(item_proxy&)` More...

Public Member Functions
	menu ()
	The default constructor. NO OTHER CONSTRUCTOR. More...

	~menu ()

item_proxy	append (std::string text_utf8, const event_fn_t &handler={})
	Appends an item to the menu. More...

void	append_splitter ()

item_proxy	insert (std::size_t pos, std::string text_utf8, const event_fn_t &handler={})
	Inserts new item at specified position. More...

void	clear ()

void	close ()
	Closes the menu. It does not destroy the menu; just close the window for the menu. More...

void	image (std::size_t pos, const paint::image &icon)

void	text (std::size_t pos, std::string text_utf8)

std::string	text (std::size_t pos) const

void	check_style (std::size_t pos, checks)

void	checked (std::size_t pos, bool)

bool	checked (std::size_t pos) const

void	enabled (std::size_t pos, bool)
	Enables or disables the mouse or keyboard input for the item. More...

bool	enabled (std::size_t pos) const

void	erase (std::size_t pos)
	Removes the item. More...

bool	link (std::size_t pos, menu &menu_obj)
	Link a menu to the item as a sub menu. More...

menu *	link (std::size_t pos) const
	Retrieves a linked sub menu of the item. More...

menu *	create_sub_menu (std::size_t pos)

void	popup (window owner, int x, int y)
	Popup the menu at the owner window. More...

void	popup_await (window owner, int x, int y)

void	answerer (std::size_t index, const event_fn_t &)
	Modify answerer of the specified item. More...

void	destroy_answer (std::function< void()>)
	Sets an answerer for the callback while the menu window is closing. More...

void	gaps (const nana::point &)
	Sets the gap between a menu and its sub menus.( Note4) More...

void	goto_next (bool forward)
	Moves the focus to the next or previous item. More...

bool	goto_submen ()
	Popup the submenu of the current item if it has a sub menu. Returns true if succeeds. More...

bool	exit_submenu ()
	Closes the current window of the sub menu. More...

std::size_t	size () const
	Return the number of items. More...

int	send_shortkey (wchar_t key)

void	pick ()

menu &	max_pixels (unsigned)
	Sets the max width in pixels of the item. More...

unsigned	max_pixels () const

menu &	item_pixels (unsigned)
	Sets the height in pixel for the items. More...

unsigned	item_pixels () const

void	renderer (const pat::cloneable< renderer_interface > &)
	Sets a user-defined renderer. More...

const pat::cloneable < renderer_interface > &	renderer () const

window	handle () const
	Returns the handle of menu window. More...

Friends
class	menu_accessor

Detailed Description

a list of items that specify options or group of options for an application.

The widget sets the shortkey that is a character behind the first of &-character in text for the item. e.g. "File(&F)" or "&File".

The type item_proxy is used for callbacking. A programmer should not take care about the object item_proxy. It is created and destroyed by menu. The definition is

         class item_proxy: nana::noncopyable
         {
           public:
                 implementation-specified constructor
                 void enabled(bool);                     //Sets the enable state of the item.
                 bool enabled() const;           //Gets the enable state of the item.
                 std::size_t index() const;      //Gets the index of the item.

           private:                      //Private data members...
         };

There is a helper for automatically popping a menu.

         class menu_popuper
         {
           public:
                                 ;//C++03
                 menu_popuper(menu&, mouse::t = mouse::right_button);
                 menu_popuper(menu&, window owner, const point& pos, 
                 mouse::t =  mouse::right_button );

                                 ;//C++11
                 menu_popuper(menu&, mouse = mouse::right_button);
                 menu_popuper(menu&, window owner, const point& pos, mouse = mouse::right_button);

                 void operator()(const eventinfo&);

         private:                        //Implemented-Specified private members

         };

 Now let's use it. There is a button, it popups the menu when it is clicked.

         #include <nana/gui/wvl.hpp>
         #include <nana/gui/widgets/button.hpp>
         #include <nana/gui/widgets/menu.hpp>

         void on_menu_item(nana::menu::item_proxy& ip)
         {
                  std::size_t index = ip.index(); //Get the index of the clicking item.
         }

         int main()
         {
                 using namespace nana::gui;
                 form fm;

                 ;//We need a menu object
                 menu mobj;
                 mobj.append ( STR("Item 0"), &on_menu_item);
                 mobj.append_splitter();
                 mobj.append ( STR("Item 1"), &on_menu_item);

                 ;//Now we need a button.
                 button btn(fm, nana::rectangle(nana::point(10, 10), nana::size(100, 25)));
                 btn.caption(STR("Popup Menu"));

                 ;//Popup the menu when right clicking the button.
                 btn.make_event<events::click>(menu_popuper(mobj));

                 ;//Or popuping the menu with a specified coordinate when any mouse button is clicked.
                 ;//btn.make_event<events::click> ( menu_popuper( mobj, btn, nana::point(0, 26),
                 ;//                                mouse::any_button );

                 fm.show();
                 exec();
         }

The gap of menu is used to specify the interval pixels between the menu and its sub menus. It affects all sub menus and all sub menus of its sub menus.

    int main()
    {
            using namespace nana::gui;

            menu mobj;
            mobj.append(STR("Item 0"));
            mobj.append(STR("Item 1"));

            mobj.gaps(nana::point(3, -2)); //Remove this statement for default gaps.

            menu * sub = mobj.create_sub_menu(0);
            sub->append(STR("Item 0"));
            sub->append(STR("Item 1"));

            sub = sub->create_sub_menu(0);
            sub->append(STR("A sub's sub menu item"));

            form fm;
            fm.make_event<events::click>(menu_popuper(mobj));
            fm.show();
            exec();
    }

When a renderer is set for a menu, it affects all sub menus of the menu and all sub menus of its all sub menus.

 An example of a user-defined renderer.

 The definition of class renderer_interface.

         class renderer_interface
         {
                 public:
                         typedef nana::paint::graphics & graph_reference;

                                 ;//C++03
                         struct state { enum t{ normal, active}; };

                                 ;//C++11
                         enum class state { normal, active };

                         struct attr
                         {
                                         ;//C++03
                                 state::t item_state;
                                         ;//C++11
                                 state item_state;

                                 bool enabled;
                                 bool checked;
                                 int check_style;
                         };

                         virtual ~renderer_interface() = 0;
                         virtual void background(graph_reference, window) = 0;
                         virtual void item     (graph_reference, const nana::rectangle&, const attr&) = 0;
                         virtual void item_image (graph_reference, const nana::point&, 
                         const nana::paint::image&) = 0;
                         virtual void item_text(graph_reference, const nana::point&, 
                         const nana::string&, unsigned pixles, const attr&) = 0;
                         virtual void sub_arrow(graph_reference, const nana::point&, 
                         unsigned pixels, const attr&) = 0;

         };

 The implementation of the user-defined renderer. In this example, the renderer 
 only provides the drawing of background and drawing of item, so that we have to 
 employ the existing renderer of a menu for other drawing methods.

 ![](renderer_of_menu.png)

         using namespace nana::gui;

         class renderer: public menu::renderer_interface
         {
            public:
                         ;//My renderer employs the existing renderer of a menu.
                 renderer(const nana::pat::cloneable_interface<renderer_interface> * rd)
                 : rdptr_(rd->clone())
                 {}

                         ;//The renderer is copy-constructable, therefore a deep-copy is required.
                 renderer(const renderer & rd)
                 : rdptr_(rd.rdptr_->clone())
                 {}
                 ~renderer() {rdptr_->self_delete();}
           private:
                 void background(graph_reference graph, window wd)
                 {
                         graph.rectangle(0xFFFFFF, true);
                         graph.rectangle(0x5DC1AC, false);

                                 ;//Makes the menu transparent, it only works under Windows with #include <windows.h>
                         HWND native = reinterpret_cast(API::root(wd));
                         DWORD ex_style = ::GetWindowLong(native, GWL_EXSTYLE);
                         ::SetWindowLong(native, GWL_EXSTYLE, ex_style | 0x00080000); // WS_EX_LAYERED
                         typedef BOOL (WINAPI *slwa_t)(HWND hwnd, COLORREF crKey, BYTE bAlpha, DWORD dwFlags);
                         slwa_t slwa = reinterpret_cast(::GetProcAddress(::GetModuleHandleA("User32.DLL"), 
                                                                                    "SetLayeredWindowAttributes"));
                         if(slwa)
                                 slwa(native, 0, 220, 0x00000002); // LWA_ALPHA
                 }

         void item(graph_reference graph, const nana::rectangle& r, const attr & atr)
         {
                 if(state::active == atr.item_state)
                         graph.rectangle(r, 0x9ADCCA, true);
         }

         void item_image(graph_reference graph, const nana::point& pos, 
                                         const nana::paint::image& img)
         {
            rdptr_->refer().item_image(graph, pos, img);
         }

         void item_text(graph_reference graph,    const nana::point& pos, 
                                    const nana::string& text, unsigned pixels, const attr& atr)
         {
                 rdptr_->refer().item_text(graph, pos, text, pixels, atr);
         }

         void sub_arrow(graph_reference graph, const nana::point& pos, 
                                    unsigned pixels,       const attr & atr)
         {
            rdptr_->refer().sub_arrow(graph, pos, pixels, atr);
         }

           private:
                 nana::pat::cloneable_interface<renderer_interface> * rdptr_;
         };

         int main()
         {
                 menu mobj;
                 mobj.append(STR("Item 0"));
                 mobj.append(STR("Item 1"));
                 mobj.create_sub_menu(1)->append(STR("A sub menu item"));

                 mobj.renderer(renderer(mobj.renderer()));
                 mobj.item_pixels(20);

                 form fm;
                 fm.make_event<events::click>(menu_popuper(mobj));
                 fm.show();
                 exec();
         }

See Also: nana::menubar.

Todo:

doc: create example

doc: make one directory for nana.Cpp03 demo and example and other for nana.Cpp11, and set it in the Doxygen project. Also, explore conditional doc generation for each variant, and also for user / developers.

Examples:: example_menu.cpp, and menu_popuper.cpp.

Member Typedef Documentation

typedef drawerbase::menu::checks nana::menu::checks

typedef drawerbase::menu::menu_item_type::event_fn_t nana::menu::event_fn_t

A callback functor type. Prototype: void(item_proxy&)

typedef drawerbase::menu::menu_item_type::item_proxy nana::menu::item_proxy

typedef drawerbase::menu::renderer_interface nana::menu::renderer_interface

Constructor & Destructor Documentation

nana::menu::menu ( )

The default constructor. NO OTHER CONSTRUCTOR.

nana::menu::~menu ( )

Member Function Documentation

void nana::menu::answerer	(	std::size_t	index,
		const event_fn_t &	fn
	)

Modify answerer of the specified item.

auto nana::menu::append	(	std::string	text_utf8,
		const event_fn_t &	handler = `{}`
	)

Appends an item to the menu.

Examples:: example_menu.cpp, menu_debug.cpp, and menu_popuper.cpp.

void nana::menu::append_splitter ( )

Examples:: menu_popuper.cpp.

void nana::menu::check_style	(	std::size_t	pos,
		checks	style
	)

void nana::menu::checked	(	std::size_t	pos,
		bool	check
	)

bool nana::menu::checked ( std::size_t pos ) const

void nana::menu::clear ( )

Erases all of the items.

void nana::menu::close ( )

Closes the menu. It does not destroy the menu; just close the window for the menu.

menu * nana::menu::create_sub_menu ( std::size_t pos )

void nana::menu::destroy_answer ( std::function< void()> fn )

Sets an answerer for the callback while the menu window is closing.

void nana::menu::enabled	(	std::size_t	pos,
		bool	enable
	)

Enables or disables the mouse or keyboard input for the item.

bool nana::menu::enabled ( std::size_t pos ) const

void nana::menu::erase ( std::size_t pos )

Removes the item.

bool nana::menu::exit_submenu ( )

Closes the current window of the sub menu.

void nana::menu::gaps ( const nana::point & pos )

Sets the gap between a menu and its sub menus.( Note4)

void nana::menu::goto_next ( bool forward )

Moves the focus to the next or previous item.

bool nana::menu::goto_submen ( )

Popup the submenu of the current item if it has a sub menu. Returns true if succeeds.

window nana::menu::handle ( ) const

Returns the handle of menu window.

Returns: handle of menu window, nullptr if the menu hasn't been popped up.

void nana::menu::image	(	std::size_t	pos,
		const paint::image &	icon
	)

auto nana::menu::insert	(	std::size_t	pos,
		std::string	text_utf8,
		const event_fn_t &	handler = `{}`
	)

Inserts new item at specified position.

It will invalidate the existing item proxies from the specified position.

Parameters

pos	The position where new item to be inserted
text_utf8	The title of item
handler	The event handler for the item.

Returns: the item proxy to the new inserted item.

menu & nana::menu::item_pixels ( unsigned px )

Sets the height in pixel for the items.

unsigned nana::menu::item_pixels ( ) const

bool nana::menu::link	(	std::size_t	pos,
		menu &	menu_obj
	)

Link a menu to the item as a sub menu.

menu * nana::menu::link ( std::size_t pos ) const

Retrieves a linked sub menu of the item.

menu & nana::menu::max_pixels ( unsigned px )

Sets the max width in pixels of the item.

unsigned nana::menu::max_pixels ( ) const

void nana::menu::pick ( )

void nana::menu::popup	(	window	owner,
		int	x,
		int	y
	)

Popup the menu at the owner window.

void nana::menu::popup_await	(	window	owner,
		int	x,
		int	y
	)

void nana::menu::renderer ( const pat::cloneable< renderer_interface > & rd )

Sets a user-defined renderer.

const pat::cloneable< menu::renderer_interface > & nana::menu::renderer ( ) const

int nana::menu::send_shortkey ( wchar_t key )

std::size_t nana::menu::size ( ) const

Return the number of items.

void nana::menu::text	(	std::size_t	pos,
		std::string	text_utf8
	)

std::string nana::menu::text ( std::size_t pos ) const

Friends And Related Function Documentation

friend class menu_accessor

friend

Classes

Public Types

Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation