xtd 0.2.0
Loading...
Searching...
No Matches
xtd::forms::menu Class Referenceabstract
Inheritance diagram for xtd::forms::menu:
xtd::forms::component xtd::iequatable< menu > xtd::object xtd::interface xtd::equality_operators< type_t, equatable_t > xtd::forms::context_menu xtd::forms::main_menu xtd::forms::menu_item

Definition

Represents the base functionality for all menus. Although tool_strip_drop_down and tool_strip_drop_down_menu replace and add functionality to the menu control of previous versions, menu is retained for both backward compatibility and future use if you choose.

Header
#include <xtd/forms/menu>
Namespace
xtd::forms
Library
xtd.forms
Remarks
This class is the base class for the main_menu, menu_item, and context_menu classes. You cannot create an instance of this class. The menus for an application consist of menu_item objects. These can contain other menu_item objects, representing submenu items. The menu_item objects can be stored in a main_menu for display as an entire menu structure for a form or a context_menu that is used to display shortcut menus. This class provides functionality that is common for all the menu classes.
Unlike many base classes, the menu class uses its derived classes to define many of its properties. If you are using your menu in a multiple-document interface (MDI) application, you can use the mdi_list_item property to specify a menu_item that displays a list of open MDI child forms in your application. The menu_items property contains a list of menu_item objects stored in the menu class. For a main_menu or context_menu, this property contains all the menu_item objects that are displayed. For a menu_item, the menu_items property represents the submenu items associated with it.
In addition to the properties that are provided for all the derived menu classes, the menu class also provides methods, such as clone_menu and merge_menu, that enable you to create new menus from existing menus, and also merge two menu structures together.
The menu class also defines the nested class menu::menu_item_collection. This class defines the collection of menu_item objects used by the menu_items property. You can use the methods of the menu::menu_item_collection class to add and remove menu items from a main_menu, context_menu, or menu_item.
Examples
application_enable_dark_mode.cpp, application_enable_light_mode.cpp, hello_world_xtd.cpp, main_menu.cpp, main_menu_create_standard_items.cpp, minesweeper.cpp, some_controls.cpp, some_system_controls.cpp, and themes.cpp.

Protected Attributes

friend menu_item
 

Public Aliases

using menu_item_collection = layout::arranged_element_collection< menu_item_ref >
 Represents a collection of menu_item objects.
 

Public Fields

static constexpr int32 find_handle
 Specifies that the find_menu_item(int32, intptr) method should search for a handle.
 
static constexpr int32 find_shortcut
 Specifies that the find_menu_item(int32, intptr) method should search for a shortcut.
 

Public Properties

intptr handle () const noexcept
 Gets a value representing the window handle for the menu.
 
virtual bool is_parent () const noexcept
 Gets a value indicating whether this menu contains any menu items.
 
const menu_itemmdi_list_item () const noexcept
 Gets a value indicating the menu_item that is used to display a list of multiple document interface (MDI) child forms.
 
const menu_item_collectionmenu_items () const noexcept
 Gets a value indicating the collection of menu_item objects associated with the menu.
 
menu_item_collectionmenu_items () noexcept
 Gets a value indicating the collection of menu_item objects associated with the menu.
 
menumenu_items (const menu_item_collection &value)
 Sets a value indicating the collection of menu_item objects associated with the menu.
 
const xtd::stringname () const noexcept
 Gets the name of the menu.
 
menuname (const xtd::string &value)
 Sets the name of the menu.
 
std::any tag () const noexcept
 Gets user-defined data associated with the control.
 
menutag (std::any value)
 Sets user-defined data associated with the control.
 

Public Methods

bool equals (const menu &) const noexcept override
 
std::optional< std::reference_wrapper< context_menu > > get_context_menu () const noexcept
 Gets the context_menu that contains this menu.
 
std::optional< std::reference_wrapper< main_menu > > get_main_menu () const noexcept
 Gets the main_menu that contains this menu.
 
virtual void merge_menu (const menu &menu_src)
 Merges the MenuItem objects of one menu with the current menu.
 
xtd::string to_string () const noexcept override
 Returns a string that represents the menu control.
 
virtual bool equals (const object &obj) const noexcept
 Determines whether the specified object is equal to the current object.
 
template<typename object_a_t , typename object_b_t >
static bool equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
 Determines whether the specified object instances are considered equal.
 

Protected constructors

 menu ()
 Initializes a new instance of the Menu class.
 
 menu (const menu_item_collection &items)
 Initializes a new instance of the Menu class.
 

Protected Methods

void clone_menu (const menu &menu_src)
 Copies the menu that is passed as a parameter to the current menu.
 
virtual intptr create_menu_handle ()=0
 Creates a new handle to the Menu.
 
virtual void destroy_menu_handle (intptr handle)
 Destroys the handle to the Menu.
 
virtual void on_item_added (size_t pos, menu_item_ref item)
 
virtual void on_item_removed (size_t pos, menu_item_ref item)
 

Additional Inherited Members

- Public Member Functions inherited from xtd::object
 object ()=default
 Create a new instance of the ultimate base class object.
 
virtual size_t get_hash_code () const noexcept
 Serves as a hash function for a particular type.
 
virtual type_object get_type () const noexcept
 Gets the type of the current instance.
 
template<typename object_t >
xtd::uptr< object_t > memberwise_clone () const
 Creates a shallow copy of the current object.
 
- Public Member Functions inherited from xtd::iequatable< menu >
virtual bool equals (const menu &) const noexcept=0
 Indicates whether the current object is equal to another object of the same type.
 
- Static Public Member Functions inherited from xtd::object
template<typename object_a_t , typename object_b_t >
static bool equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
 Determines whether the specified object instances are considered equal.
 
template<typename object_a_t , typename object_b_t >
static bool reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
 Determines whether the specified object instances are the same instance.
 
- Protected Member Functions inherited from xtd::forms::component
 component ()
 Initialises a new instance of the component class.
 
virtual bool can_raise_events () const noexcept
 Gets a value indicating whether the component can raise an event.
 
bool design_mode () const noexcept
 Gets a value that indicates whether the component is currently in design mode.
 

Member Typedef Documentation

◆ menu_item_collection

Constructor & Destructor Documentation

◆ menu() [1/2]

xtd::forms::menu::menu ( )
protected

Initializes a new instance of the Menu class.

Remarks
Since menu is an abstract class, only inherited classes can call the menu constructor.

◆ menu() [2/2]

xtd::forms::menu::menu ( const menu_item_collection items)
explicitprotected

Initializes a new instance of the Menu class.

Parameters
itemsAn array of type MenuItem containing the objects to add to the menu.
Remarks
Since menu is an abstract class, only inherited classes can call the menu constructor.

Member Function Documentation

◆ handle()

intptr xtd::forms::menu::handle ( ) const
noexcept

Gets a value representing the window handle for the menu.

Returns
The HMENU value of the menu.
Remarks
You can use this property to obtain the handle to the menu to perform special operations to the menu outside of the functionality provided by this class or its derived classes.

◆ is_parent()

virtual bool xtd::forms::menu::is_parent ( ) const
virtualnoexcept

Gets a value indicating whether this menu contains any menu items.

Returns
true if this menu contains menu_item objects; otherwise, false. The default is false.

Reimplemented in xtd::forms::menu_item.

◆ mdi_list_item()

const menu_item & xtd::forms::menu::mdi_list_item ( ) const
noexcept

Gets a value indicating the menu_item that is used to display a list of multiple document interface (MDI) child forms.

Returns
A MenuItem that represents the menu item displaying a list of MDI child forms that are open in the application.
Remarks
You can use this property to determine whether a menu_item has been specified to display the list of open child windows in an MDI application. To use a specific menu_item as an MDI list, set the mdi_list property in the menu_item to be used.

◆ menu_items() [1/3]

const menu_item_collection & xtd::forms::menu::menu_items ( ) const
noexcept

Gets a value indicating the collection of menu_item objects associated with the menu.

Returns
A menu::menu_item_collection that represents the list of menu_item objects stored in the menu.
Remarks
You can use this property to obtain a reference to the list of menu items that are currently stored in the menu. For main_menu and context_menu objects, the menu_items property contains the entire menu structure in the control. For the menu_item class, the menu_items property contains the list of submenu items associated with the menu_item. With the reference to the collection of menu items for the menu (provided by this property), you can add and remove menu items, determine the total number of menu items, and clear the list of menu items from the collection. For more information on maintaining the menu item collection for a menu, see the xtd::forms::menu::menu_item_collection documentation.

◆ menu_items() [2/3]

menu_item_collection & xtd::forms::menu::menu_items ( )
noexcept

Gets a value indicating the collection of menu_item objects associated with the menu.

Returns
A menu::menu_item_collection that represents the list of menu_item objects stored in the menu.
Remarks
You can use this property to obtain a reference to the list of menu items that are currently stored in the menu. For main_menu and context_menu objects, the menu_items property contains the entire menu structure in the control. For the menu_item class, the menu_items property contains the list of submenu items associated with the menu_item. With the reference to the collection of menu items for the menu (provided by this property), you can add and remove menu items, determine the total number of menu items, and clear the list of menu items from the collection. For more information on maintaining the menu item collection for a menu, see the xtd::forms::menu::menu_item_collection documentation.

◆ menu_items() [3/3]

menu & xtd::forms::menu::menu_items ( const menu_item_collection value)

Sets a value indicating the collection of menu_item objects associated with the menu.

Parameters
valueA menu::menu_item_collection that represents the list of menu_item objects stored in the menu.
Returns
Current menu class.
Remarks
You can use this property to obtain a reference to the list of menu items that are currently stored in the menu. For main_menu and context_menu objects, the menu_items property contains the entire menu structure in the control. For the menu_item class, the menu_items property contains the list of submenu items associated with the menu_item. With the reference to the collection of menu items for the menu (provided by this property), you can add and remove menu items, determine the total number of menu items, and clear the list of menu items from the collection. For more information on maintaining the menu item collection for a menu, see the xtd::forms::menu::menu_item_collection documentation.

◆ name() [1/2]

const xtd::string & xtd::forms::menu::name ( ) const
noexcept

Gets the name of the menu.

Returns
A string representing the name.
Remarks
At design time, this property is set to the programmatic identifier of the control. However, this property has no bearing on the control at run time.

◆ name() [2/2]

menu & xtd::forms::menu::name ( const xtd::string value)

Sets the name of the menu.

Parameters
valueA string representing the name.
Returns
Current menu class.
Remarks
At design time, this property is set to the programmatic identifier of the control. However, this property has no bearing on the control at run time.

◆ tag() [1/2]

std::any xtd::forms::menu::tag ( ) const
noexcept

Gets user-defined data associated with the control.

Returns
An object representing the data.

◆ tag() [2/2]

menu & xtd::forms::menu::tag ( std::any  value)

Sets user-defined data associated with the control.

Parameters
valueAn object representing the data.
Returns
Current menu class.

◆ get_context_menu()

std::optional< std::reference_wrapper< context_menu > > xtd::forms::menu::get_context_menu ( ) const
noexcept

Gets the context_menu that contains this menu.

Returns
The context_menu that contains this menu. The default is no value.
Remarks
This method allows you to obtain a reference to the context_menu that this menu is contained in. This property returns no value if the menu is not contained in a context_menu. This can occur if the menu is contained in a menu_item or main_menu, or if the menu is not contained in any menu. You can use this property to determine whether a menu is currently being used, and also to determine where.

◆ get_main_menu()

std::optional< std::reference_wrapper< main_menu > > xtd::forms::menu::get_main_menu ( ) const
noexcept

Gets the main_menu that contains this menu.

Returns
The main_menu that contains this menu. The default is has no value.
Remarks
This method allows you to obtain a reference to the main_menu that this menu is contained in. This property returns no value if the menu is not contained in a main_menu. This can occur if the menu is contained in a menu_item or context_menu, or if the menu is not contained in any menu. You can use this property to determine whether a menu is currently being used, and also to determine where.

◆ merge_menu()

virtual void xtd::forms::menu::merge_menu ( const menu menu_src)
virtual

Merges the MenuItem objects of one menu with the current menu.

Parameters
menu_srcThe menu whose menu items are merged with the menu items of the current menu.
Exceptions
std::invalid_argumentIt was attempted to merge the menu with itself.

◆ to_string()

xtd::string xtd::forms::menu::to_string ( ) const
overridevirtualnoexcept

Returns a string that represents the menu control.

Returns
A string that represents the current menu.
Remarks
The to_string method returns a string that includes the type and the number of items in the menu_items property of the control.

Reimplemented from xtd::object.

Reimplemented in xtd::forms::menu_item.

◆ clone_menu()

void xtd::forms::menu::clone_menu ( const menu menu_src)
protected

Copies the menu that is passed as a parameter to the current menu.

Parameters
menu_srcThe Menu to copy.
Remarks
This method copies the entire list of menuItem objects (stored in the menu passed in to menu_src) into the current menu. You can use this method in your derived class to clone menu_item objects. They can then be reused by other classes that derive from menu, such as main_menu, context_menu, and menu_item.

◆ create_menu_handle()

virtual intptr xtd::forms::menu::create_menu_handle ( )
protectedpure virtual

Creates a new handle to the Menu.

Returns
A handle to the menu if the method succeeds; otherwise, 0.

Implemented in xtd::forms::context_menu, xtd::forms::main_menu, and xtd::forms::menu_item.

◆ destroy_menu_handle()

virtual void xtd::forms::menu::destroy_menu_handle ( intptr  handle)
protectedvirtual

Destroys the handle to the Menu.

Parameters
handleA handle to the menu.

Reimplemented in xtd::forms::context_menu, xtd::forms::main_menu, and xtd::forms::menu_item.

◆ equals() [1/2]

virtual bool xtd::object::equals ( const object obj) const
virtualnoexcept

Determines whether the specified object is equal to the current object.

Parameters
objThe object to compare with the current object.
Returns
true if the specified object is equal to the current object. otherwise, false.
Examples
The following code example compares the current instance with another object.
#include <xtd/console>
using namespace xtd;
auto main() -> int {
auto object1 = new_ptr<object>();
auto object2 = new_ptr<object>();
auto object3 = object2;
console::write_line(object1->equals(*object3));
console::write_line(*object1 == *object3);
object3 = object1;
console::write_line(object1->equals(*object3));
console::write_line(*object1 == *object3);
}
// This code produces the following output :
//
// false
// false
// true
// true
static void write_line()
Writes the current line terminator to the standard output stream using the specified format informati...
The xtd namespace contains all fundamental classes to access Hardware, Os, System,...
Definition xtd_about_box.h:10

Reimplemented from xtd::object.

◆ equals() [2/2]

template<typename object_a_t , typename object_b_t >
static bool xtd::object::equals ( const object_a_t &  object_a,
const object_b_t &  object_b 
)
inlinestaticnoexcept

Determines whether the specified object instances are considered equal.

Parameters
object_aThe first object to compare.
object_bThe second object to compare.
Returns
true if object_a is the same instance as object_b or if both are null references or if object_a(object_b) returns true. otherwise, false.
Examples
The following code example compares different objects.
#include <xtd/console>
using namespace xtd;
auto main() -> int {
string s1 = "Tom";
string s2 = "Carol";
console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
s1 = "Tom";
s2 = "Tom";
console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
s1 = "";
s2 = "Tom";
console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
s1 = "Carol";
s2 = "";
console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
s1 = "";
s2 = "";
console::write_line("object::equals(\"{0}\", \"{1}\") => {2}", s1, s2, object::equals(s1, s2));
}
// This code produces the following output :
//
// object::equals("Tom", "Carol") => false
// object::equals("Tom", "Tom") => true
// object::equals("", "Tom") => false
// object::equals("Carol", "") => false
// object::equals("", "") => true
virtual bool equals(const object &obj) const noexcept
Determines whether the specified object is equal to the current object.

Member Data Documentation

◆ find_handle

constexpr int32 xtd::forms::menu::find_handle
staticconstexpr

Specifies that the find_menu_item(int32, intptr) method should search for a handle.

◆ find_shortcut

constexpr int32 xtd::forms::menu::find_shortcut
staticconstexpr

Specifies that the find_menu_item(int32, intptr) method should search for a shortcut.


The documentation for this class was generated from the following file: