D++ (DPP)
C++ Discord API Bot Library
dpp::component Class Reference

Represents the component object. A component is a clickable button or drop down list within a discord message, where the buttons emit on_button_click events when the user interacts with them. More...

+ Inheritance diagram for dpp::component:
+ Collaboration diagram for dpp::component:

Public Member Functions

 component ()
 Constructor. More...
 
virtual ~component ()=default
 Destructor. More...
 
componentadd_channel_type (uint8_t ct)
 Add a channel type to include in the channel select component (dpp::cot_channel_selectmenu) More...
 
componentset_type (component_type ct)
 Set the type of the component. Button components (type dpp::cot_button) should always be contained within an action row (type dpp::cot_action_row). As described below, many of the other methods automatically set this to the correct type so usually you should not need to manually call component::set_type(). More...
 
componentset_sku_id (dpp::snowflake sku)
 Set the SKU ID for a premium upsell button This is only valid for premium upsell buttons of type cos_premium. It indicates which premium package to link to when the button is clicked. More...
 
componentset_text_style (text_style_type ts)
 Set the text style of a text component. More...
 
componentset_label (std::string_view label)
 Set the label of the component, e.g. button text. For action rows, this field is ignored. Setting the label will auto-set the type to dpp::cot_button. More...
 
componentset_default_value (std::string_view val)
 Set the default value of the text input component. For action rows, this field is ignored. Setting the value will auto-set the type to dpp::cot_text. More...
 
componentset_url (std::string_view url)
 Set the url for dpp::cos_link types. Calling this function sets the style to dpp::cos_link and the type to dpp::cot_button. More...
 
componentset_style (component_style cs)
 Set the style of the component, e.g. button colour. For action rows, this field is ignored. Setting the style will auto-set the type to dpp::cot_button. More...
 
componentset_id (std::string_view id)
 Set the id of the component. For action rows, this field is ignored. Setting the id will auto-set the type to dpp::cot_button. More...
 
componentset_disabled (bool disable)
 Set the component to disabled. Defaults to false on all created components. More...
 
componentset_required (bool require)
 Set if this component is required. Defaults to false on all created components. More...
 
componentset_placeholder (std::string_view placeholder)
 Set the placeholder. More...
 
componentset_min_values (uint32_t min_values)
 Set the minimum number of items that must be chosen for a select menu. More...
 
componentset_max_values (uint32_t max_values)
 Set the maximum number of items that can be chosen for a select menu. More...
 
componentset_min_length (uint32_t min_l)
 Set the minimum input length for a text input. More...
 
componentset_max_length (uint32_t max_l)
 Set the maximum input length for a text input. More...
 
componentadd_select_option (const select_option &option)
 Add a select option. More...
 
componentadd_component (const component &c)
 Add a sub-component, only valid for action rows. Adding subcomponents to a component will automatically set this component's type to dpp::cot_action_row. More...
 
componentadd_default_value (const snowflake id, const component_default_value_type type)
 Add a default value. More...
 
componentset_emoji (std::string_view name, dpp::snowflake id=0, bool animated=false)
 Set the emoji of the current sub-component. More...
 
template<typename U = T, typename = decltype(std::declval<U&>().fill_from_json_impl(std::declval<nlohmann::json*>()))>
T & fill_from_json (nlohmann::json *j)
 Convert object from nlohmann::json. More...
 
template<typename U = T, typename = decltype(std::declval<U&>().to_json_impl(bool{}))>
auto to_json (bool with_id=false) const
 Convert object to nlohmann::json. More...
 
template<typename U = T, typename = decltype(std::declval<U&>().to_json_impl(bool{}))>
std::string build_json (bool with_id=false) const
 Convert object to json string. More...
 

Public Attributes

component_type type
 Component type, either a button or action row. More...
 
std::vector< componentcomponents
 Sub components, buttons on an action row. More...
 
std::string label
 Component label (for buttons, text inputs). Maximum of 80 characters. More...
 
component_style style
 Component style (for buttons). More...
 
text_style_type text_style
 Text style (for text inputs). More...
 
std::string custom_id
 Component id (for buttons, menus, text inputs). Maximum of 100 characters. More...
 
std::string url
 URL for link types (dpp::cos_link). Maximum of 512 characters. More...
 
dpp::snowflake sku_id
 The SKU ID for premium upsell buttons. More...
 
std::string placeholder
 Placeholder text for select menus and text inputs (max 150 characters) More...
 
int32_t min_values
 Minimum number of items that must be chosen for a select menu (0-25). More...
 
int32_t max_values
 Maximum number of items that can be chosen for a select menu (0-25). More...
 
int32_t min_length
 Minimum length for text input (0-4000) More...
 
int32_t max_length
 Maximum length for text input (1-4000) More...
 
std::vector< select_optionoptions
 Select options for select menus. More...
 
std::vector< uint8_tchannel_types
 List of channel types (dpp::channel_type) to include in the channel select component (dpp::cot_channel_selectmenu) More...
 
std::vector< component_default_valuedefault_values
 List of default values for auto-populated select menu components. More...
 
bool disabled
 Disabled flag (for buttons) More...
 
bool required
 Whether the text input is required to be filled. More...
 
std::variant< std::monostate, std::string, int64_t, double > value
 Value of the modal. Filled or valid when populated from an on_form_submit event, or from the set_value function. More...
 
partial_emoji emoji
 The emoji for this component. More...
 

Protected Member Functions

componentfill_from_json_impl (nlohmann::json *j)
 

Friends

struct json_interface< component >
 

Detailed Description

Represents the component object. A component is a clickable button or drop down list within a discord message, where the buttons emit on_button_click events when the user interacts with them.

You should generally define one component object and then insert one or more additional components into it using component::add_component(), so that the parent object is an action row and the child objects are buttons.

Constructor & Destructor Documentation

◆ component()

dpp::component::component ( )

Constructor.

◆ ~component()

virtual dpp::component::~component ( )
virtualdefault

Destructor.

Member Function Documentation

◆ add_channel_type()

component& dpp::component::add_channel_type ( uint8_t  ct)

Add a channel type to include in the channel select component (dpp::cot_channel_selectmenu)

Parameters
ctThe dpp::channel_type
Returns
component& reference to self

◆ add_component()

component& dpp::component::add_component ( const component c)

Add a sub-component, only valid for action rows. Adding subcomponents to a component will automatically set this component's type to dpp::cot_action_row.

Parameters
cThe sub-component to add
Returns
component& reference to self

◆ add_default_value()

component& dpp::component::add_default_value ( const snowflake  id,
const component_default_value_type  type 
)

Add a default value.

Parameters
idDefault value. ID of a user, role, or channel
typeThe type this default value represents

◆ add_select_option()

component& dpp::component::add_select_option ( const select_option option)

Add a select option.

Parameters
optionoption to add
Returns
component& Reference to self

◆ build_json()

template<typename T >
template<typename U = T, typename = decltype(std::declval<U&>().to_json_impl(bool{}))>
std::string dpp::json_interface< T >::build_json ( bool  with_id = false) const
inlineinherited

Convert object to json string.

Parameters
with_idWhether to include the ID or not
Note
Some fields are conditionally filled, do not rely on all fields being present
Returns
std::string Json built from the structure

◆ fill_from_json()

template<typename T >
template<typename U = T, typename = decltype(std::declval<U&>().fill_from_json_impl(std::declval<nlohmann::json*>()))>
T& dpp::json_interface< T >::fill_from_json ( nlohmann::json *  j)
inlineinherited

Convert object from nlohmann::json.

Parameters
jnlohmann::json object
Returns
T& Reference to self for fluent calling

◆ fill_from_json_impl()

component& dpp::component::fill_from_json_impl ( nlohmann::json *  j)
protected

Read class values from json object

Parameters
jA json object to read from
Returns
A reference to self

◆ set_default_value()

component& dpp::component::set_default_value ( std::string_view  val)

Set the default value of the text input component. For action rows, this field is ignored. Setting the value will auto-set the type to dpp::cot_text.

Parameters
valValue text to set. It will be truncated to the maximum length of 4000 UTF-8 characters.
Returns
component& Reference to self

◆ set_disabled()

component& dpp::component::set_disabled ( bool  disable)

Set the component to disabled. Defaults to false on all created components.

Parameters
disableTrue to disable the component, False to enable the component.
Returns
component& Reference to self

◆ set_emoji()

component& dpp::component::set_emoji ( std::string_view  name,
dpp::snowflake  id = 0,
bool  animated = false 
)

Set the emoji of the current sub-component.

Warning
Only valid for buttons.
Note
Adding an emoji to a component will automatically set this components type to dpp::cot_button. One or both of name and id must be set. For a built in unicode emoji, you only need set name, and should set it to a unicode character e.g. "😄". For custom emojis, set the name to the name of the emoji on the guild, and the id to the emoji's ID. Setting the animated boolean is only valid for custom emojis.
Parameters
nameEmoji name, or unicode character to use
idEmoji id, for custom emojis only.
animatedTrue if the custom emoji is animated.
Returns
component& Reference to self

◆ set_id()

component& dpp::component::set_id ( std::string_view  id)

Set the id of the component. For action rows, this field is ignored. Setting the id will auto-set the type to dpp::cot_button.

Parameters
idCustom ID string to set. This ID will be sent for any on_button_click events related to the button.
Note
The maximum length of the Custom ID is 100 UTF-8 codepoints. If your Custom ID is longer than this, it will be truncated.
Returns
component& Reference to self

◆ set_label()

component& dpp::component::set_label ( std::string_view  label)

Set the label of the component, e.g. button text. For action rows, this field is ignored. Setting the label will auto-set the type to dpp::cot_button.

Parameters
labelLabel text to set. It will be truncated to the maximum length of 80 UTF-8 characters.
Returns
component& Reference to self

◆ set_max_length()

component& dpp::component::set_max_length ( uint32_t  max_l)

Set the maximum input length for a text input.

Parameters
max_lmax length to set (1-4000)
Returns
component& Reference to self

◆ set_max_values()

component& dpp::component::set_max_values ( uint32_t  max_values)

Set the maximum number of items that can be chosen for a select menu.

Parameters
max_valuesmax value to set (0-25)
Returns
component& Reference to self

◆ set_min_length()

component& dpp::component::set_min_length ( uint32_t  min_l)

Set the minimum input length for a text input.

Parameters
min_lmin length to set (0-4000)
Returns
component& Reference to self

◆ set_min_values()

component& dpp::component::set_min_values ( uint32_t  min_values)

Set the minimum number of items that must be chosen for a select menu.

Parameters
min_valuesmin value to set (0-25)
Returns
component& Reference to self

◆ set_placeholder()

component& dpp::component::set_placeholder ( std::string_view  placeholder)

Set the placeholder.

Parameters
placeholderplaceholder string. It will be truncated to the maximum length of 150 UTF-8 characters for select menus, and 100 UTF-8 characters for modals.
Returns
component& Reference to self

◆ set_required()

component& dpp::component::set_required ( bool  require)

Set if this component is required. Defaults to false on all created components.

Parameters
requireTrue to require this, false to make it optional.
Returns
component& Reference to self

◆ set_sku_id()

component& dpp::component::set_sku_id ( dpp::snowflake  sku)

Set the SKU ID for a premium upsell button This is only valid for premium upsell buttons of type cos_premium. It indicates which premium package to link to when the button is clicked.

Parameters
skuThe SKU ID
Returns
component& reference to self

◆ set_style()

component& dpp::component::set_style ( component_style  cs)

Set the style of the component, e.g. button colour. For action rows, this field is ignored. Setting the style will auto-set the type to dpp::cot_button.

Parameters
csComponent style to set
Returns
component& reference to self

◆ set_text_style()

component& dpp::component::set_text_style ( text_style_type  ts)

Set the text style of a text component.

Note
Sets type to cot_text
Parameters
tsText style type to set
Returns
component& reference to self

◆ set_type()

component& dpp::component::set_type ( component_type  ct)

Set the type of the component. Button components (type dpp::cot_button) should always be contained within an action row (type dpp::cot_action_row). As described below, many of the other methods automatically set this to the correct type so usually you should not need to manually call component::set_type().

Parameters
ctThe component type
Returns
component& reference to self

◆ set_url()

component& dpp::component::set_url ( std::string_view  url)

Set the url for dpp::cos_link types. Calling this function sets the style to dpp::cos_link and the type to dpp::cot_button.

Parameters
urlURL to set. It will be truncated to the maximum length of 512 UTF-8 characters.
Returns
component& reference to self.

◆ to_json()

template<typename T >
template<typename U = T, typename = decltype(std::declval<U&>().to_json_impl(bool{}))>
auto dpp::json_interface< T >::to_json ( bool  with_id = false) const
inlineinherited

Convert object to nlohmann::json.

Parameters
with_idWhether to include the ID or not
Note
Some fields are conditionally filled, do not rely on all fields being present
Returns
json Json built from the structure

Friends And Related Function Documentation

◆ json_interface< component >

friend struct json_interface< component >
friend

Member Data Documentation

◆ channel_types

std::vector<uint8_t> dpp::component::channel_types

List of channel types (dpp::channel_type) to include in the channel select component (dpp::cot_channel_selectmenu)

◆ components

std::vector<component> dpp::component::components

Sub components, buttons on an action row.

◆ custom_id

std::string dpp::component::custom_id

Component id (for buttons, menus, text inputs). Maximum of 100 characters.

◆ default_values

std::vector<component_default_value> dpp::component::default_values

List of default values for auto-populated select menu components.

Note
The amount of default values must be in the range defined by dpp::component::min_values and dpp::component::max_values.
Warning
Only available for auto-populated select menu components, which include dpp::cot_user_selectmenu, dpp::cot_role_selectmenu, dpp::cot_mentionable_selectmenu, and dpp::cot_channel_selectmenu components.

◆ disabled

bool dpp::component::disabled

Disabled flag (for buttons)

◆ emoji

partial_emoji dpp::component::emoji

The emoji for this component.

◆ label

std::string dpp::component::label

Component label (for buttons, text inputs). Maximum of 80 characters.

◆ max_length

int32_t dpp::component::max_length

Maximum length for text input (1-4000)

◆ max_values

int32_t dpp::component::max_values

Maximum number of items that can be chosen for a select menu (0-25).

Note
Use -1 to not set this. This is done by default.

◆ min_length

int32_t dpp::component::min_length

Minimum length for text input (0-4000)

◆ min_values

int32_t dpp::component::min_values

Minimum number of items that must be chosen for a select menu (0-25).

Note
Use -1 to not set this. This is done by default.

◆ options

std::vector<select_option> dpp::component::options

Select options for select menus.

Warning
Only required and available for select menus of type dpp::cot_selectmenu

◆ placeholder

std::string dpp::component::placeholder

Placeholder text for select menus and text inputs (max 150 characters)

◆ required

bool dpp::component::required

Whether the text input is required to be filled.

◆ sku_id

dpp::snowflake dpp::component::sku_id

The SKU ID for premium upsell buttons.

◆ style

component_style dpp::component::style

Component style (for buttons).

◆ text_style

text_style_type dpp::component::text_style

Text style (for text inputs).

◆ type

component_type dpp::component::type

Component type, either a button or action row.

◆ url

std::string dpp::component::url

URL for link types (dpp::cos_link). Maximum of 512 characters.

◆ value

std::variant<std::monostate, std::string, int64_t, double> dpp::component::value

Value of the modal. Filled or valid when populated from an on_form_submit event, or from the set_value function.

D++ Library version 9.0.13D++ Library version 9.0.12D++ Library version 9.0.11D++ Library version 9.0.10D++ Library version 9.0.9D++ Library version 9.0.8D++ Library version 9.0.7D++ Library version 9.0.6D++ Library version 9.0.5D++ Library version 9.0.4D++ Library version 9.0.3D++ Library version 9.0.2D++ Library version 9.0.1D++ Library version 9.0.0D++ Library version 1.0.2D++ Library version 1.0.1D++ Library version 1.0.0