xtd::forms::tool_bar_button Class Reference

Inheritance diagram for xtd::forms::tool_bar_button:

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/drawing/texts>
#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/timer>
#include <xtd/forms/tool_bar>
#include <xtd/forms/tool_bar_images>
 
using namespace xtd;
using namespace xtd::drawing;
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(string::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(string::format("Button {} clicked, pushed = {}", e.button().text(), e.button().pushed()));
      else
        list_box1.items().push_back(string::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(string::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 {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(texts::new_(), 0);
    tool_bar_button open_tool_bar_button = tool_bar_button::create_push_button(texts::open(), 1);
    tool_bar_button save_tool_bar_button = tool_bar_button::create_push_button(texts::save(), 2);
    tool_bar_button print_tool_bar_button = tool_bar_button::create_push_button(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(texts::cut(), 4);
    tool_bar_button copy_tool_bar_button = tool_bar_button::create_push_button(texts::copy(), 5);
    tool_bar_button paste_tool_bar_button = tool_bar_button::create_push_button(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(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.

Public Constructors
	tool_bar_button ()
	Initialises a new instance of xtd::forms::tool_bar_button class.
	tool_bar_button (const xtd::string &text)
	Initializes a new instance of the xtd::forms::tool_bar_button class and displays the assigned text on the button.

Public Properties
std::optional< xtd::forms::control_ref >	control () const noexcept
	Gets the control to be displayed in the control toolbar button.
tool_bar_button &	control (const xtd::forms::control &value)
	Sets the control to be displayed in the control toolbar button.
tool_bar_button &	control (std::nullptr_t value)
	Resets the control to be displayed in the control toolbar button.
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.
tool_bar_button &	drop_down_menu (const xtd::forms::context_menu &value)
	Sets the menu to be displayed in the drop-down toolbar button.
tool_bar_button &	drop_down_menu (std::nullptr_t value)
	Resets the menu to be displayed in the drop-down toolbar button.
bool	enabled () const noexcept
	Gets a value indicating whether the button is enabled.
tool_bar_button &	enabled (bool value)
	Sets a value indicating whether the button is enabled.
size_t	image_index () const noexcept
	Gets the index value of the image assigned to the button.
tool_bar_button &	image_index (size_t value)
	Sets the index value of the image assigned to the button.
const xtd::string &	name () const noexcept
	Gets the name of the button.
tool_bar_button &	name (const xtd::string &value)
	Sets the name of the button.
std::optional< std::reference_wrapper< xtd::forms::tool_bar > >	parent () const noexcept
	Gets the toolbar control that the toolbar button is assigned to.
bool	pushed () const noexcept
	Gets a value indicating whether a toggle-style toolbar button is currently in the pushed state.
tool_bar_button &	pushed (bool value)
	Sets a value indicating whether a toggle-style toolbar button is currently in the pushed state.
const xtd::drawing::rectangle &	rectangle () const noexcept
	Gets the bounding rectangle for a toolbar button.
xtd::forms::tool_bar_button_style	style () const noexcept
	Gets the style of the toolbar button.
tool_bar_button &	style (xtd::forms::tool_bar_button_style value)
	Sets the style of the toolbar button.
std::any	tag () const noexcept
	Gets the object that contains data about the toolbar button.
tool_bar_button &	tag (std::any value)
	Sets the object that contains data about the toolbar button.
const xtd::string &	text () const noexcept
	Gets the text displayed on the toolbar button.
tool_bar_button &	text (const xtd::string &value)
	Sets the text displayed on the toolbar button.
const xtd::string &	tool_tip_text () const noexcept
	Gets the text that appears as a xtd::forms::tool_tip for the button.
tool_bar_button &	tool_tip_text (const xtd::string &value)
	Sets the text that appears as a xtd::forms::tool_tip for the button.
bool	visible () const noexcept
	Gets a value indicating whether the toolbar button is visible.
tool_bar_button &	visible (bool value)
	Sets a value indicating whether the toolbar button is visible.

Public Methods
bool	equals (const tool_bar_button &other) const noexcept override
xtd::string	to_string () const noexcept override
	Returns a string that represents the xtd::forms::tool_bar_button 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.

Public Static Methods
static tool_bar_button	create_control (const xtd::string &text, const xtd::forms::control &control)
	A factory to create a control toolbar button with specified text and control.
static tool_bar_button	create_control (const xtd::forms::control &control)
	A factory to create a control toolbar button with specified control.
static tool_bar_button	create_drop_down_button (const xtd::string &text, const xtd::forms::context_menu &drop_down_menu)
	A factory to create a drop-down toolbar button with specified text and context menu.
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.
static tool_bar_button	create_drop_down_button (const xtd::string &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.
static tool_bar_button	create_push_button (const xtd::string &text)
	A factory to create a toolbar button with specified text.
static tool_bar_button	create_push_button (size_t image_index)
	A factory to create a toolbar button with specified image index.
static tool_bar_button	create_push_button (const xtd::string &text, size_t image_index)
	A factory to create a toolbar button with specified text and image index.
static tool_bar_button	create_separator ()
	A factory to create a toolbar separator.
static tool_bar_button	create_stretchable_separator ()
	A factory to create a toolbar stretchable separator.
static tool_bar_button	create_toggle_button (const xtd::string &text)
	A factory to create a toolbar toggle button with specified text.
static tool_bar_button	create_toggle_button (size_t image_index)
	A factory to create a toolbar toggle button with specified image index.
static tool_bar_button	create_toggle_button (const xtd::string &text, size_t image_index)
	A factory to create a toolbar toggle button with specified text and image index.

Protected Methods
xtd::uptr< xtd::object >	clone () const override
	Creates a new object that is a copy of the current instance.

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::iclonable
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.
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.

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::string &  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.

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::string & 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::string &

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.

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.

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::string & 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.

text() [2/2]

tool_bar_button & xtd::forms::tool_bar_button::text

(

const xtd::string &

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.

tool_tip_text() [1/2]

const xtd::string & 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::string &

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.

to_string()

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

overridevirtualnoexcept

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

Returns

A xtd::string 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.

create_control() [1/2]

static tool_bar_button xtd::forms::tool_bar_button::create_control ( const xtd::string &  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.

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::string &  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.

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::string &  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::string &  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.

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::string &  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.

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.

create_toggle_button() [1/3]

static tool_bar_button xtd::forms::tool_bar_button::create_toggle_button ( const xtd::string &  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.

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::string &  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.

clone()

xtd::uptr< xtd::object > xtd::forms::tool_bar_button::clone ( ) const

overrideprotectedvirtual

Creates a new object that is a copy of the current instance.

Returns

A new object that is a copy of this instance.

Notes to Implementers

All controls must be override the clone method.

Implements xtd::iclonable.

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

obj	The 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

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_a	The first object to compare.
object_b	The 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

---

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

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