Definition

Represents a toolbar button.

Header: #include <xtd/forms/tool_bar_button>

Namespace: xtd::forms

Library: xtd.forms

Examples: The following code example demonstrates the use of xtd::forms::tool_bar_button control.
#include <xtd/forms/application>
#include <xtd/forms/choice>
#include <xtd/forms/form>
#include <xtd/forms/list_box>
#include <xtd/forms/progress_bar>
#include <xtd/forms/system_texts>
#include <xtd/forms/timer>
#include <xtd/forms/tool_bar>
#include <xtd/forms/tool_bar_images>
using namespace xtd;
using namespace xtd::forms;
namespace tool_bar_example {
class form1 : public form {
public:
form1() {
text("Toolbar example");
client_size({820, 500});
controls().push_back_range({list_box1, tool_bar2, tool_bar1});
tool_bar(tool_bar1);
active_control(list_box1);

list_box1.dock(dock_style::fill);

choice1.items().push_back_range({"Item1", "Item2", "Item3", "Item4", "Item5", "Item6", "Item7", "Item8", "Item9", "Item10"});
choice1.selected_index(0);
choice1.selected_value_changed += [&] {
list_box1.items().push_back(ustring::format("{} selected", choice1.selected_item()));
list_box1.selected_index(list_box1.items().size() - 1);
};

progress_bar1.width(150);

progress_timer1.interval_milliseconds(50);
progress_timer1.start();
progress_timer1.tick += [&] {
progress_bar1.value(progress_bar1.value() < progress_bar1.maximum() ? progress_bar1.value() + 1 : progress_bar1.minimum());
};

tool_bar1.image_list().images().push_back_range({tool_bar_images::file_new(), tool_bar_images::file_open(), tool_bar_images::file_save(), tool_bar_images::file_print(), tool_bar_images::edit_cut(), tool_bar_images::edit_copy(), tool_bar_images::edit_paste(), tool_bar_images::help()});
tool_bar1.buttons().push_back_range({new_tool_bar_button, open_tool_bar_button, save_tool_bar_button, print_tool_bar_button, tool_bar1_separator1, cut_tool_bar_button, copy_tool_bar_button, paste_tool_bar_button, tool_bar1_separator2, choice_tool_bar_button, tool_bar1_separator3, help_tool_bar_button});
tool_bar1.button_click += {*this, &form1::on_tool_bar_button_click};

tool_bar2.dock(dock_style::bottom);
tool_bar2.show_text(true);
tool_bar2.text_align(xtd::forms::tool_bar_text_align::right);
tool_bar2.image_list().image_size({24, 24});
tool_bar2.image_list().images().push_back_range({tool_bar_images::from_name("media-playback-start"), tool_bar_images::from_name("media-skip-backward"), tool_bar_images::from_name("media-playback-stop"), tool_bar_images::from_name("media-skip-forward"), tool_bar_images::from_name("media-record"), tool_bar_images::from_name("media-eject")});
tool_bar2.buttons().push_back_range({play_tool_bar_button, tool_bar2_separator1, skip_backward_tool_bar_button, stop_tool_bar_button, skip_forward_tool_bar_button, tool_bar2_separator2, record_tool_bar_button, tool_bar2_separator3, progress_tool_bar_button, tool_bar2_separator4, eject_tool_bar_button});
tool_bar2.button_click += {*this, &form1::on_tool_bar_button_click};

record_tool_bar_button.enabled(false);
}

private:
void on_tool_bar_button_click(object& sender, const tool_bar_button_click_event_args& e) {
if (e.button().style() == tool_bar_button_style::toggle_button)
list_box1.items().push_back(ustring::format("Button {} clicked, pushed = {}", e.button().text(), e.button().pushed()));
else
list_box1.items().push_back(ustring::format("Button {} clicked", e.button().text()));
list_box1.selected_index(list_box1.items().size() - 1);
}

void on_menu_click(object& sender, const event_args& e) {
list_box1.items().push_back(ustring::format("Menu item {} clicked", as<menu_item>(sender).text()));
list_box1.selected_index(list_box1.items().size() - 1);
}

list_box list_box1;

menu_item context_help_context_menu_item {"Help context", {*this, &form1::on_menu_click}};
menu_item context_help_index_menu_item {"Help index", {*this, &form1::on_menu_click}};
menu_item context_help_search_menu_item {"Help search", {*this, &form1::on_menu_click}};
menu_item context_separator_menu_item {"-"};
menu_item context_about_menu_item {system_texts::about(), {*this, &form1::on_menu_click}};
forms::context_menu context_menu1 {context_help_context_menu_item, context_help_index_menu_item, context_help_search_menu_item, context_separator_menu_item, context_about_menu_item};

forms::tool_bar tool_bar1;
choice choice1;
tool_bar_button new_tool_bar_button = tool_bar_button::create_push_button(system_texts::new_(), 0);
tool_bar_button open_tool_bar_button = tool_bar_button::create_push_button(system_texts::open(), 1);
tool_bar_button save_tool_bar_button = tool_bar_button::create_push_button(system_texts::save(), 2);
tool_bar_button print_tool_bar_button = tool_bar_button::create_push_button(system_texts::print(), 3);
tool_bar_button tool_bar1_separator1 = tool_bar_button::create_separator();
tool_bar_button cut_tool_bar_button = tool_bar_button::create_push_button(system_texts::cut(), 4);
tool_bar_button copy_tool_bar_button = tool_bar_button::create_push_button(system_texts::copy(), 5);
tool_bar_button paste_tool_bar_button = tool_bar_button::create_push_button(system_texts::paste(), 6);
tool_bar_button tool_bar1_separator2 = tool_bar_button::create_separator();
tool_bar_button choice_tool_bar_button = tool_bar_button::create_control("Items", choice1);
tool_bar_button tool_bar1_separator3 = tool_bar_button::create_stretchable_separator();
tool_bar_button help_tool_bar_button = tool_bar_button::create_drop_down_button(system_texts::help(), 7, context_menu1);

forms::tool_bar tool_bar2;
progress_bar progress_bar1;
timer progress_timer1;
tool_bar_button play_tool_bar_button = tool_bar_button::create_push_button("&Play", 0);
tool_bar_button tool_bar2_separator1 = tool_bar_button::create_separator();
tool_bar_button skip_backward_tool_bar_button = tool_bar_button::create_push_button("Skip &Backward", 1);
tool_bar_button stop_tool_bar_button = tool_bar_button::create_push_button("S&top", 2);
tool_bar_button skip_forward_tool_bar_button = tool_bar_button::create_push_button("Skip &Forward", 3);
tool_bar_button tool_bar2_separator2 = tool_bar_button::create_separator();
tool_bar_button record_tool_bar_button = tool_bar_button::create_push_button("&Record", 4);
tool_bar_button tool_bar2_separator3 = tool_bar_button::create_separator();
tool_bar_button progress_tool_bar_button = tool_bar_button::create_control(progress_bar1);
tool_bar_button tool_bar2_separator4 = tool_bar_button::create_stretchable_separator();
tool_bar_button eject_tool_bar_button = tool_bar_button::create_toggle_button("&Eject", 5);
};
}
auto main()->int {
application::run(tool_bar_example::form1 {});
}

Remarks: xtd::forms::tool_bar_button controls are parented by xtd::forms::tool_bar controls. Common properties to set once the toolbar button has been created are xtd::forms::tool_bar_button::text and xtd::forms::tool_bar_button::image_index. Set the xtd::forms::tool_bar_button::text property of the button to display text beneath or to the right of the image. To assign images to the buttons by creating an xtd::forms::image_list, assigning it to the xtd::forms::tool_bar::image_list property of the toolbar; then assign the image index value to the xtd::forms::tool_bar_button::image_index property of the button.; To change the appearance of the toolbar buttons assigned to the toolbar, set the xtd::forms::tool_bar::appearance property of the parent toolbar control. The xtd::forms::tool_bar_appearance::flat appearance gives the buttons a flat appearance. As the mouse pointer moves over the buttons, their appearance changes to three-dimensional. Button separators appear as lines rather than spaces between the buttons when the buttons have a flat appearance. If the xtd::forms::tool_bar::appearance property is set to xtd::forms::tool_bar_appearance::normal, the buttons appear raised and three-dimensional, and the separators appear as a gap between the buttons.; You can assign a xtd::forms::context_menu to a button if the xtd::forms::tool_bar_button::style property is set to xtd::forms::tool_bar_button_style::drop_down. When the button is clicked, the assigned menu is displayed.; To create a collection of xtd::forms::tool_bar_button controls to display on a xtd::forms::tool_bar, add the buttons individually by using the xtd::forms::tool_bar::tool_bar_button_collection::push_back method of the xtd::forms::tool_bar::buttons property. Alternatively, you can add several toolbar buttons using the xtd::forms::tool_bar::tool_bar_button_collection.push_back_range method.

Examples:: application_enable_dark_mode.cpp, application_enable_light_mode.cpp, some_controls.cpp, some_system_controls.cpp, themes.cpp, and tool_bar.cpp.

Constructors
	tool_bar_button ()
	Initialises a new instance of xtd::forms::tool_bar_button class. More...

	tool_bar_button (const xtd::ustring &text)
	Initializes a new instance of the xtd::forms::tool_bar_button class and displays the assigned text on the button. More...

Properties
std::optional< xtd::forms::control_ref >	control () const noexcept
	Gets the control to be displayed in the control toolbar button. More...

tool_bar_button &	control (const xtd::forms::control &value)
	Sets the control to be displayed in the control toolbar button. More...

tool_bar_button &	control (std::nullptr_t value)
	Resets the control to be displayed in the control toolbar button. More...

std::optional< std::reference_wrapper< xtd::forms::context_menu > >	drop_down_menu () const noexcept
	Gets the menu to be displayed in the drop-down toolbar button. More...

tool_bar_button &	drop_down_menu (const xtd::forms::context_menu &value)
	Sets the menu to be displayed in the drop-down toolbar button. More...

tool_bar_button &	drop_down_menu (std::nullptr_t value)
	Resets the menu to be displayed in the drop-down toolbar button. More...

bool	enabled () const noexcept
	Gets a value indicating whether the button is enabled. More...

tool_bar_button &	enabled (bool value)
	Sets a value indicating whether the button is enabled. More...

size_t	image_index () const noexcept
	Gets the index value of the image assigned to the button. More...

tool_bar_button &	image_index (size_t value)
	Sets the index value of the image assigned to the button. More...

const xtd::ustring &	name () const noexcept
	Gets the name of the button. More...

tool_bar_button &	name (const xtd::ustring &value)
	Sets the name of the button. More...

std::optional< std::reference_wrapper< xtd::forms::tool_bar > >	parent () const noexcept
	Gets the toolbar control that the toolbar button is assigned to. More...

bool	pushed () const noexcept
	Gets a value indicating whether a toggle-style toolbar button is currently in the pushed state. More...

tool_bar_button &	pushed (bool value)
	Sets a value indicating whether a toggle-style toolbar button is currently in the pushed state. More...

const xtd::drawing::rectangle &	rectangle () const noexcept
	Gets the bounding rectangle for a toolbar button. More...

xtd::forms::tool_bar_button_style	style () const noexcept
	Gets the style of the toolbar button. More...

tool_bar_button &	style (xtd::forms::tool_bar_button_style value)
	Sets the style of the toolbar button. More...

std::any	tag () const noexcept
	Gets the object that contains data about the toolbar button. More...

tool_bar_button &	tag (std::any value)
	Sets the object that contains data about the toolbar button. More...

const xtd::ustring &	text () const noexcept
	Gets the text displayed on the toolbar button. More...

tool_bar_button &	text (const xtd::ustring &value)
	Sets the text displayed on the toolbar button. More...

const xtd::ustring &	tool_tip_text () const noexcept
	Gets the text that appears as a xtd::forms::tool_tip for the button. More...

tool_bar_button &	tool_tip_text (const xtd::ustring &value)
	Sets the text that appears as a xtd::forms::tool_tip for the button. More...

bool	visible () const noexcept
	Gets a value indicating whether the toolbar button is visible. More...

tool_bar_button &	visible (bool value)
	Sets a value indicating whether the toolbar button is visible. More...

Methods
bool	equals (const tool_bar_button &other) const noexcept override

xtd::ustring	to_string () const noexcept override
	Returns a string that represents the xtd::forms::tool_bar_button control. More...

static tool_bar_button	create_control (const xtd::ustring &text, const xtd::forms::control &control)
	A factory to create a control toolbar button with specified text and control. More...

static tool_bar_button	create_control (const xtd::forms::control &control)
	A factory to create a control toolbar button with specified control. More...

static tool_bar_button	create_drop_down_button (const xtd::ustring &text, const xtd::forms::context_menu &drop_down_menu)
	A factory to create a drop-down toolbar button with specified text and context menu. More...

static tool_bar_button	create_drop_down_button (size_t image_index, const xtd::forms::context_menu &drop_down_menu)
	A factory to create a drop-down toolbar button with specified image index and context menu. More...

static tool_bar_button	create_drop_down_button (const xtd::ustring &text, size_t image_index, const xtd::forms::context_menu &drop_down_menu)
	A factory to create a drop-down toolbar button with specified text, image index and context menu. More...

static tool_bar_button	create_push_button (const xtd::ustring &text)
	A factory to create a toolbar button with specified text. More...

static tool_bar_button	create_push_button (size_t image_index)
	A factory to create a toolbar button with specified image index. More...

static tool_bar_button	create_push_button (const xtd::ustring &text, size_t image_index)
	A factory to create a toolbar button with specified text and image index. More...

static tool_bar_button	create_separator ()
	A factory to create a toolbar separator. More...

static tool_bar_button	create_stretchable_separator ()
	A factory to create a toolbar stretchable separator. More...

static tool_bar_button	create_toggle_button (const xtd::ustring &text)
	A factory to create a toolbar toggle button with specified text. More...

static tool_bar_button	create_toggle_button (size_t image_index)
	A factory to create a toolbar toggle button with specified image index. More...

static tool_bar_button	create_toggle_button (const xtd::ustring &text, size_t image_index)
	A factory to create a toolbar toggle button with specified text and image index. More...

Additional Inherited Members
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object. More...

bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object. More...

virtual size_t	get_hash_code () const noexcept
	Serves as a hash function for a particular type. More...

virtual type_object	get_type () const noexcept
	Gets the type of the current instance. More...

template<typename object_t >
std::unique_ptr< object_t >	memberwise_clone () const noexcept
	Creates a shallow copy of the current object. More...

Public Member Functions inherited from xtd::iequatable< tool_bar_button >
virtual bool	equals (const tool_bar_button &) const noexcept=0
	Indicates whether the current object is equal to another object of the same type. More...

Static Public Member Functions inherited from xtd::object
static bool	equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are considered equal. More...

static bool	reference_equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are the same instance. More...

Protected Member Functions inherited from xtd::forms::component
	component ()
	Initialises a new instance of the component class. More...

virtual bool	can_raise_events () const noexcept
	Gets a value indicating whether the component can raise an event. More...

bool	design_mode () const noexcept
	Gets a value that indicates whether the component is currently in design mode. More...

Constructor & Destructor Documentation

◆ tool_bar_button() [1/2]

xtd::forms::tool_bar_button::tool_bar_button ( )

Initialises a new instance of xtd::forms::tool_bar_button class.

Remarks: A newly created xtd::forms::tool_bar_button has no default xtd::forms::tool_bar_button::text or xtd::drawing::image assigned to it. The button's default style is xtd::tool_bar_button_style::push_button.

◆ tool_bar_button() [2/2]

xtd::forms::tool_bar_button::tool_bar_button ( const xtd::ustring & text )

explicit

Initializes a new instance of the xtd::forms::tool_bar_button class and displays the assigned text on the button.

Parameters

text	The text to display on the new xtd::forms::tool_bar_button.

Remarks: The newly created xtd::forms::tool_bar_button has no xtd::drawing::image assigned assigned to it. The button's default style is xtd::tool_bar_button_style::push_button. The text parameter is assigned to the xtd::forms::tool_bar_button::text property and is displayed on the new toolbar button control.

Member Function Documentation

◆ control() [1/3]

std::optional<xtd::forms::control_ref> xtd::forms::tool_bar_button::control ( ) const

noexcept

Gets the control to be displayed in the control toolbar button.

Returns: A xtd::forms::control to be displayed in the control toolbar button. The default is std::nullopt.

Remarks: You can specify a xtd::forms::control to be displayed. This property is not used unless the xtd::forms::tool_bar_button::style property value is set to xtd::forms::tool_bar_button_style::control.

◆ control() [2/3]

tool_bar_button& xtd::forms::tool_bar_button::control ( const xtd::forms::control & value )

Sets the control to be displayed in the control toolbar button.

Parameters

value A xtd::forms::control to be displayed in the control toolbar button. The default is std::nullopt.

Returns: This current instance.

Remarks: You can specify a xtd::forms::control to be displayed. This property is not used unless the xtd::forms::tool_bar_button::style property value is set to xtd::forms::tool_bar_button_style::control.

◆ control() [3/3]

tool_bar_button& xtd::forms::tool_bar_button::control ( std::nullptr_t value )

Resets the control to be displayed in the control toolbar button.

Parameters

value nullptr.

Returns: This current instance.

Remarks: You can specify a xtd::forms::control to be displayed. This property is not used unless the xtd::forms::tool_bar_button::style property value is set to xtd::forms::tool_bar_button_style::control.

◆ create_control() [1/2]

static tool_bar_button xtd::forms::tool_bar_button::create_control	(	const xtd::ustring &	text,
		const xtd::forms::control &	control
	)

static

A factory to create a control toolbar button with specified text and control.

Parameters

text	The text displayed on the toolbar button.
control	A xtd::forms::control to be displayed in the control toolbar button.

Returns: New xtd::forms::tool_bar_button created.

Examples:: tool_bar.cpp.

◆ create_control() [2/2]

static tool_bar_button xtd::forms::tool_bar_button::create_control ( const xtd::forms::control & control )

static

A factory to create a control toolbar button with specified control.

Parameters

control A xtd::forms::control to be displayed in the control toolbar button.

Returns: New xtd::forms::tool_bar_button created.

◆ create_drop_down_button() [1/3]

static tool_bar_button xtd::forms::tool_bar_button::create_drop_down_button	(	const xtd::ustring &	text,
		const xtd::forms::context_menu &	drop_down_menu
	)

static

A factory to create a drop-down toolbar button with specified text and context menu.

Parameters

text	The text displayed on the toolbar button.
drop_down_menu	A xtd::forms::context_menu to be displayed in the drop-down toolbar button.

Returns: New xtd::forms::tool_bar_button created.

Examples:: tool_bar.cpp.

◆ create_drop_down_button() [2/3]

static tool_bar_button xtd::forms::tool_bar_button::create_drop_down_button	(	size_t	image_index,
		const xtd::forms::context_menu &	drop_down_menu
	)

static

A factory to create a drop-down toolbar button with specified image index and context menu.

Parameters

image_index	The index value of the xtd::drawing::image assigned to the toolbar button.
drop_down_menu	A xtd::forms::context_menu to be displayed in the drop-down toolbar button.

Returns: New xtd::forms::tool_bar_button created.

◆ create_drop_down_button() [3/3]

static tool_bar_button xtd::forms::tool_bar_button::create_drop_down_button	(	const xtd::ustring &	text,
		size_t	image_index,
		const xtd::forms::context_menu &	drop_down_menu
	)

static

A factory to create a drop-down toolbar button with specified text, image index and context menu.

Parameters

text	The text displayed on the toolbar button.
image_index	The index value of the xtd::drawing::image assigned to the toolbar button.
drop_down_menu	A xtd::forms::context_menu to be displayed in the drop-down toolbar button.

Returns: New xtd::forms::tool_bar_button created.

◆ create_push_button() [1/3]

static tool_bar_button xtd::forms::tool_bar_button::create_push_button ( const xtd::ustring & text )

static

A factory to create a toolbar button with specified text.

Parameters

text	The text displayed on the toolbar button.

Returns: New xtd::forms::tool_bar_button created.

Examples:: tool_bar.cpp.

◆ create_push_button() [2/3]

static tool_bar_button xtd::forms::tool_bar_button::create_push_button ( size_t image_index )

static

A factory to create a toolbar button with specified image index.

Parameters

image_index The index value of the xtd::drawing::image assigned to the toolbar button.

Returns: New xtd::forms::tool_bar_button created.

◆ create_push_button() [3/3]

static tool_bar_button xtd::forms::tool_bar_button::create_push_button	(	const xtd::ustring &	text,
		size_t	image_index
	)

static

A factory to create a toolbar button with specified text and image index.

Parameters

text	The text displayed on the toolbar button.
image_index	The index value of the xtd::drawing::image assigned to the toolbar button.

Returns: New xtd::forms::tool_bar_button created.

◆ create_separator()

static tool_bar_button xtd::forms::tool_bar_button::create_separator ( )

static

A factory to create a toolbar separator.

Returns: New xtd::forms::tool_bar_button created.

Examples:: tool_bar.cpp.

◆ create_stretchable_separator()

static tool_bar_button xtd::forms::tool_bar_button::create_stretchable_separator ( )

static

A factory to create a toolbar stretchable separator.

Returns: New xtd::forms::tool_bar_button created.

Examples:: tool_bar.cpp.

◆ create_toggle_button() [1/3]

static tool_bar_button xtd::forms::tool_bar_button::create_toggle_button ( const xtd::ustring & text )

static

A factory to create a toolbar toggle button with specified text.

Parameters

text	The text displayed on the toolbar button.

Returns: New xtd::forms::tool_bar_button created.

Examples:: tool_bar.cpp.

◆ create_toggle_button() [2/3]

static tool_bar_button xtd::forms::tool_bar_button::create_toggle_button ( size_t image_index )

static

A factory to create a toolbar toggle button with specified image index.

Parameters

image_index The index value of the xtd::drawing::image assigned to the toolbar button.

Returns: New xtd::forms::tool_bar_button created.

◆ create_toggle_button() [3/3]

static tool_bar_button xtd::forms::tool_bar_button::create_toggle_button	(	const xtd::ustring &	text,
		size_t	image_index
	)

static

A factory to create a toolbar toggle button with specified text and image index.

Parameters

text	The text displayed on the toolbar button.
image_index	The index value of the xtd::drawing::image assigned to the toolbar button.

Returns: New xtd::forms::tool_bar_button created.

◆ drop_down_menu() [1/3]

std::optional<std::reference_wrapper<xtd::forms::context_menu> > xtd::forms::tool_bar_button::drop_down_menu ( ) const

noexcept

Gets the menu to be displayed in the drop-down toolbar button.

Returns: A xtd::forms::context_menu to be displayed in the drop-down toolbar button. The default is std::nullopt.

Remarks: You can specify a xtd::forms::context_menu to be displayed when the drop-down button is clicked. This property is not used unless the xtd::forms::tool_bar_button::style property value is set to xtd::forms::tool_bar_button_style::drop_down_button.

◆ drop_down_menu() [2/3]

tool_bar_button& xtd::forms::tool_bar_button::drop_down_menu ( const xtd::forms::context_menu & value )

Sets the menu to be displayed in the drop-down toolbar button.

Parameters

value A xtd::forms::context_menu to be displayed in the drop-down toolbar button. The default is std::nullopt.

Returns: This current instance.

Remarks: You can specify a xtd::forms::context_menu to be displayed when the drop-down button is clicked. This property is not used unless the xtd::forms::tool_bar_button::style property value is set to xtd::forms::tool_bar_button_style::drop_down_button.

◆ drop_down_menu() [3/3]

tool_bar_button& xtd::forms::tool_bar_button::drop_down_menu ( std::nullptr_t value )

Resets the menu to be displayed in the drop-down toolbar button.

Parameters

value nullptr.

Returns: This current instance.

Remarks: You can specify a xtd::forms::context_menu to be displayed when the drop-down button is clicked. This property is not used unless the xtd::forms::tool_bar_button::style property value is set to xtd::forms::tool_bar_button_style::drop_down_button.

◆ enabled() [1/2]

bool xtd::forms::tool_bar_button::enabled ( ) const

noexcept

Gets a value indicating whether the button is enabled.

Returns: true if the button is enabled; otherwise, false. The default is true.

Remarks: When the xtd::forms::tool_bar_button::enabled property is set to false, the toolbar button cannot be clicked, and the button's appearance changes. The xtd::drawing::image and xtd::forms::tool_bar_button::text assigned to the button appear grayed out. If the image or text has multiple colors, they display in a monochromatic gray.

◆ enabled() [2/2]

tool_bar_button& xtd::forms::tool_bar_button::enabled ( bool value )

Sets a value indicating whether the button is enabled.

Parameters

value true if the button is enabled; otherwise, false. The default is true.

Returns: This current instance.

Remarks: When the xtd::forms::tool_bar_button::enabled property is set to false, the toolbar button cannot be clicked, and the button's appearance changes. The xtd::drawing::image and xtd::forms::tool_bar_button::text assigned to the button appear grayed out. If the image or text has multiple colors, they display in a monochromatic gray.

◆ image_index() [1/2]

size_t xtd::forms::tool_bar_button::image_index ( ) const

noexcept

Gets the index value of the image assigned to the button.

Returns: The index value of the xtd::drawing::image assigned to the toolbar button. The default is xtd::forms::image_list::image_collection::npos.

Remarks: The xtd::forms::tool_bar_button::image_index value references the indexed value of the images in an xtd::forms::tool_bar::image_list assigned to the parent xtd::forms::tool_bar control.

◆ image_index() [2/2]

tool_bar_button& xtd::forms::tool_bar_button::image_index ( size_t value )

Sets the index value of the image assigned to the button.

Parameters

value The index value of the xtd::drawing::image assigned to the toolbar button. The default is xtd::forms::image_list::image_collection::npos.

Returns: This current instance.

Remarks: The xtd::forms::tool_bar_button::image_index value references the indexed value of the images in an xtd::forms::tool_bar::image_list assigned to the parent xtd::forms::tool_bar control.

◆ name() [1/2]

const xtd::ustring& xtd::forms::tool_bar_button::name ( ) const

noexcept

Gets the name of the button.

Returns: The name of the button.

Remarks: You can use the button name as a key to retrieve the xtd::forms::tool_bar_button from the xtd::forms::tool_bar::buttons collection of a xtd::forms::tool_bar control.

◆ name() [2/2]

tool_bar_button& xtd::forms::tool_bar_button::name ( const xtd::ustring & value )

Sets the name of the button.

Parameters

value The name of the button.

Returns: This current instance.

Remarks: You can use the button name as a key to retrieve the xtd::forms::tool_bar_button from the xtd::forms::tool_bar::buttons collection of a xtd::forms::tool_bar control.

◆ parent()

std::optional<std::reference_wrapper<xtd::forms::tool_bar> > xtd::forms::tool_bar_button::parent ( ) const

noexcept

Gets the toolbar control that the toolbar button is assigned to.

Returns: The xtd::forms::tool_bar control that the xtd::forms::tool_bar_button is assigned to.

◆ pushed() [1/2]

bool xtd::forms::tool_bar_button::pushed ( ) const

noexcept

Gets a value indicating whether a toggle-style toolbar button is currently in the pushed state.

Returns: rue if a toggle-style toolbar button is currently in the pushed state; otherwise, false. The default is false.

Remarks: When xtd::forms::tool_bar_button::pushed is set to true, the toolbar button appears sunken or inset relative to the other buttons. This property has no effect unless the xtd::forms::tool_bar_button::style is set to xtd::forms::tool_bar_button_style::toggle_button.

Examples:: tool_bar.cpp.

◆ pushed() [2/2]

tool_bar_button& xtd::forms::tool_bar_button::pushed ( bool value )

Sets a value indicating whether a toggle-style toolbar button is currently in the pushed state.

Parameters

value rue if a toggle-style toolbar button is currently in the pushed state; otherwise, false. The default is false.

Returns: This current instance.

Remarks: When xtd::forms::tool_bar_button::pushed is set to true, the toolbar button appears sunken or inset relative to the other buttons. This property has no effect unless the xtd::forms::tool_bar_button::style is set to xtd::forms::tool_bar_button_style::toggle_button.

◆ rectangle()

const xtd::drawing::rectangle& xtd::forms::tool_bar_button::rectangle ( ) const

noexcept

Gets the bounding rectangle for a toolbar button.

Returns: The bounding xtd::drawing::rectangle for a toolbar button.

Remarks: If the xtd::forms::tool_bar and the current button are both xtd::forms::tool_bar_button::visible, then this property retrieves the bounding rectangle the button is currently contained in.

◆ style() [1/2]

xtd::forms::tool_bar_button_style xtd::forms::tool_bar_button::style ( ) const

noexcept

Gets the style of the toolbar button.

Returns: One of the xtd::forms::tool_bar_button_style values. The default is xtd::forms::tool_bar_button_style::push_button.

Remarks: If the button xtd::forms::tool_bar_button::style is set to xtd::forms::tool_bar_button::drop_down_button you can specify a xtd::forms::menu_contex to be displayed when the drop-down button is pressed. If the style is set to xtd::forms::tool_bar_button_style::separator, the toolbar button appears as a button separator and not as a button. The xtd::forms::tool_bar_button_style::toggle_button style causes the toolbar button to act like a toggle button; it can be in an on or off state. If the style is set to xtd::forms::tool_bar_button_style::stretchable_separator, the toolbar button appears as a stretchable button separator and not as a button. If the button xtd::forms::tool_bar_button::style is set to xtd::forms::tool_bar_button::control you can specify a xtd::forms::control to be displayed when the button.

Examples:: tool_bar.cpp.

◆ style() [2/2]

tool_bar_button& xtd::forms::tool_bar_button::style ( xtd::forms::tool_bar_button_style value )

Sets the style of the toolbar button.

Parameters

value One of the xtd::forms::tool_bar_button_style values. The default is xtd::forms::tool_bar_button_style::push_button.

Returns: This current instance.

Remarks: If the button xtd::forms::tool_bar_button::style is set to xtd::forms::tool_bar_button::drop_down_button you can specify a xtd::forms::menu_contex to be displayed when the drop-down button is pressed. If the style is set to xtd::forms::tool_bar_button_style::separator, the toolbar button appears as a button separator and not as a button. The xtd::forms::tool_bar_button_style::toggle_button style causes the toolbar button to act like a toggle button; it can be in an on or off state. If the style is set to xtd::forms::tool_bar_button_style::stretchable_separator, the toolbar button appears as a stretchable button separator and not as a button. If the button xtd::forms::tool_bar_button::style is set to xtd::forms::tool_bar_button::control you can specify a xtd::forms::control to be displayed when the button.

◆ tag() [1/2]

std::any xtd::forms::tool_bar_button::tag ( ) const

noexcept

Gets the object that contains data about the toolbar button.

Returns: An std::any that contains data about the toolbar button. The default is empty.

Remarks: Retrieves or assigns the data currently associated with the toolbar button. Any std::any type can be assigned to this property.

◆ tag() [2/2]

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

Sets the object that contains data about the toolbar button.

Parameters

value An std::any that contains data about the toolbar button. The default is empty.

Returns: This current instance.

Remarks: Retrieves or assigns the data currently associated with the toolbar button. Any std::any type can be assigned to this property.

◆ text() [1/2]

const xtd::ustring& xtd::forms::tool_bar_button::text ( ) const

noexcept

Gets the text displayed on the toolbar button.

Returns: The text displayed on the toolbar button. The default is an empty string ("").

Remarks: The default the xtd::forms::tool_bar_button::text property value is an empty string ("") unless you created the control with the xtd::forms::tool_bar constructor that accepts the text string as a parameter. The orientation of the text on the toolbar button is determined by the xtd::forms::tool_bar::text_align property of the button's parentxtd::forms::tool_bar, which can be set to one of the xtd::forms::tool_bar_text_align enumeration values. The orientation is in relation to the image assigned to the button. If no image is assigned to the button, there will be space left for one on the surface of the toolbar button.

Examples:: tool_bar.cpp.

◆ text() [2/2]

tool_bar_button& xtd::forms::tool_bar_button::text ( const xtd::ustring & value )

Sets the text displayed on the toolbar button.

Parameters

value The text displayed on the toolbar button. The default is an empty string ("").

Returns: This current instance.

Remarks: The default the xtd::forms::tool_bar_button::text property value is an empty string ("") unless you created the control with the xtd::forms::tool_bar constructor that accepts the text string as a parameter. The orientation of the text on the toolbar button is determined by the xtd::forms::tool_bar::text_align property of the button's parentxtd::forms::tool_bar, which can be set to one of the xtd::forms::tool_bar_text_align enumeration values. The orientation is in relation to the image assigned to the button. If no image is assigned to the button, there will be space left for one on the surface of the toolbar button.

◆ to_string()

xtd::ustring xtd::forms::tool_bar_button::to_string ( ) const

overridevirtualnoexcept

Returns a string that represents the xtd::forms::tool_bar_button control.

Returns: A xtd::ustring that represents the current xtd::forms::tool_bar_button.

Remarks: The xtd::forms::tool_bar_button::to_string method returns a string that includes the type and the value of the xtd::forms::tool_bar_button::style and xtd::forms::tool_bar_button::text properties.

Reimplemented from xtd::object.

◆ tool_tip_text() [1/2]

const xtd::ustring& xtd::forms::tool_bar_button::tool_tip_text ( ) const

noexcept

Gets the text that appears as a xtd::forms::tool_tip for the button.

Returns: The text that is displayed when the mouse pointer moves over the toolbar button. The default is an empty string ("").

Remarks: To enable the display of the xtd::forms::tool_tip text when the mouse pointer is moved over the button, set the xtd::forms::tool_bar::show_tool_tips property of the button's parent xtd::forms::tool_bar to true.

◆ tool_tip_text() [2/2]

tool_bar_button& xtd::forms::tool_bar_button::tool_tip_text ( const xtd::ustring & value )

Sets the text that appears as a xtd::forms::tool_tip for the button.

Parameters

value The text that is displayed when the mouse pointer moves over the toolbar button. The default is an empty string ("").

Returns: This current instance.

Remarks: To enable the display of the xtd::forms::tool_tip text when the mouse pointer is moved over the button, set the xtd::forms::tool_bar::show_tool_tips property of the button's parent xtd::forms::tool_bar to true.

◆ visible() [1/2]

bool xtd::forms::tool_bar_button::visible ( ) const

noexcept

Gets a value indicating whether the toolbar button is visible.

Returns: true if the toolbar button is visible; otherwise, false. The default is true.

Remarks: If the toolbar button is not visible, it will not be displayed on the toolbar, and therefore cannot receive user input.

◆ visible() [2/2]

tool_bar_button& xtd::forms::tool_bar_button::visible ( bool value )

Sets a value indicating whether the toolbar button is visible.

Parameters

value true if the toolbar button is visible; otherwise, false. The default is true.

Returns: This current instance.

Remarks: If the toolbar button is not visible, it will not be displayed on the toolbar, and therefore cannot receive user input.

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

xtd.forms/include/xtd/forms/tool_bar_button.h

Definition

Constructors

Properties

Methods

Additional Inherited Members

Constructor & Destructor Documentation

◆ tool_bar_button() [1/2]

◆ tool_bar_button() [2/2]

Member Function Documentation

◆ control() [1/3]

◆ control() [2/3]

◆ control() [3/3]

◆ create_control() [1/2]

◆ create_control() [2/2]

◆ create_drop_down_button() [1/3]

◆ create_drop_down_button() [2/3]

◆ create_drop_down_button() [3/3]

◆ create_push_button() [1/3]

◆ create_push_button() [2/3]

◆ create_push_button() [3/3]

◆ create_separator()

◆ create_stretchable_separator()

◆ create_toggle_button() [1/3]

◆ create_toggle_button() [2/3]

◆ create_toggle_button() [3/3]

◆ drop_down_menu() [1/3]

◆ drop_down_menu() [2/3]

◆ drop_down_menu() [3/3]

◆ enabled() [1/2]

◆ enabled() [2/2]

◆ image_index() [1/2]

◆ image_index() [2/2]

◆ name() [1/2]

◆ name() [2/2]

◆ parent()

◆ pushed() [1/2]

◆ pushed() [2/2]

◆ rectangle()

◆ style() [1/2]

◆ style() [2/2]

◆ tag() [1/2]

◆ tag() [2/2]

◆ text() [1/2]

◆ text() [2/2]

◆ to_string()

◆ tool_tip_text() [1/2]

◆ tool_tip_text() [2/2]

◆ visible() [1/2]

◆ visible() [2/2]