| D++ (DPP) C++ Discord API Bot Library

Search
Loading...
Searching...
No Matches
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...

`#include <message.h>`

Inheritance diagram for dpp::component:
[legend]
Collaboration diagram for dpp::component:
[legend]

## Public Member Functions

| component ()
| Constructor.
virtual | ~component ()=default
| Destructor.
component & | add_channel_type (uint8_t ct)
| Add a channel type to include in the channel select component (dpp::cot_channel_selectmenu).
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.
component & | add_component_v2 (const component &c)
| Add a sub-component, does not automatically create action rows. This should be used for components v2 where you do not want to add action rows automatically.
component & | add_default_value (const snowflake id, const component_default_value_type type)
| Add a default value.
component & | add_media_gallery_item (const component &media_gallery_item)
| Add a media gallery item to a media gallery type (v2).
component & | add_select_option (const select_option &option)
| Add a select option.
std::string | build_json (bool with_id=false) const
| Convert object to json string.
component & | fill_from_json (nlohmann::json *j)
| Convert object from nlohmann::json.
component & | set_accent (uint32_t accent_colour)
| Set accent colour for container type (v2).
component & | set_accessory (const component &accessory_component)
| Set accessory component for components which support it. Can be a button or a thumbnail image.
component & | set_content (const std::string &text)
| For text content types, set content.
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.
component & | set_description (const std::string &text)
| For media types, set description.
component & | set_disabled (bool disable)
| Set the component to disabled. Defaults to false on all created components.
component & | set_divider (bool divider)
| Set divider visibility for separator type (v2).
component & | set_emoji (std::string_view name, dpp::snowflake id=0, bool animated=false)
| Set the emoji of the current sub-component.
component & | set_file (std::string_view attachment_url)
| Set the attachment url for file type components. The format of the attachment url should be of the type "attachment://...".
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.
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.
component & | set_max_length (uint32_t max_l)
| Set the maximum input length for a text input.
component & | set_max_values (uint32_t max_values)
| Set the maximum number of items that can be chosen for a select menu.
component & | set_min_length (uint32_t min_l)
| Set the minimum input length for a text input.
component & | set_min_values (uint32_t min_values)
| Set the minimum number of items that must be chosen for a select menu.
component & | set_placeholder (std::string_view placeholder)
| Set the placeholder.
component & | set_required (bool require)
| Set if this component is required. Defaults to false on all created components.
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.
component & | set_spacing (separator_spacing sep_spacing)
| Set separator spacing for separator type (v2).
component & | set_spoiler (bool spoiler_enable)
| For media and file component types, set spoiler status.
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.
component & | set_text_style (text_style_type ts)
| Set the text style of a text component.
component & | set_thumbnail (std::string_view url)
| Set component thumbnail for thumbnail type (v2.
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().
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.
auto | to_json (bool with_id=false) const
| Convert object to nlohmann::json.

## Public Attributes

std::optional< uint32_t > | accent
| Accent colour for container types (v2).
std::shared_ptr< component > | accessory
| accessory component for components which support it (v2) Can be a button or a thumbnail.
std::vector< uint8_t > | channel_types
| List of channel types (dpp::channel_type) to include in the channel select component (dpp::cot_channel_selectmenu).
std::vector< component > | components
| Sub components, buttons on an action row.
std::string | content
| Text content for section and text display types (v2).
std::string | custom_id
| Component id (for buttons, menus, text inputs). Maximum of 100 characters.
std::vector< component_default_value > | default_values
| List of default values for auto-populated select menu components.
std::string | description
| Description for media items (v2).
bool | disabled
| Disabled flag (for buttons).
partial_emoji | emoji
| The emoji for this component.
std::optional< embed_image > | file
| Unfurled file URL for file objects (v2) Should be in the format "attachment://...".
bool | is_divider
| can be set for separator types (v2)
std::string | label
| Component label (for buttons, text inputs). Maximum of 80 characters.
int32_t | max_length
| Maximum length for text input (1-4000).
int32_t | max_values
| Maximum number of items that can be chosen for a select menu (0-25).
std::vector< std::shared_ptr< component > > | media_gallery_items
| Media gallery items for media galleries (v2).
int32_t | min_length
| Minimum length for text input (0-4000).
int32_t | min_values
| Minimum number of items that must be chosen for a select menu (0-25).
std::vector< select_option > | options
| Select options for select menus.
std::string | placeholder
| Placeholder text for select menus and text inputs (max 150 characters).
bool | required
| Whether the text input is required to be filled.
dpp::snowflake | sku_id
| The SKU ID for premium upsell buttons.
separator_spacing | spacing
| Valid for separator types (v2).
bool | spoiler
| Spoiler state for media and file items.
component_style | style
| Component style (for buttons).
text_style_type | text_style
| Text style (for text inputs).
std::optional< embed_image > | thumbnail
| Unfurled media for thumbnail objects (v2).
component_type | type
| Component type, either a button or action row.
std::string | url
| URL for link types (dpp::cos_link). Maximum of 512 characters.
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.

## Protected Member Functions

component & | fill_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 | ( |  | ) |

virtual default

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

  ct | The 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.

Note
  Automatic creation of action rows is retained for backwards compatibility with components v1. If you want to add components v2, and do not want automatic creation of action rows, use dpp::component::add_component_v2() instead.

Parameters

  c | The sub-component to add

Returns
  component& reference to self

## ◆ add_component_v2()

component & dpp::component::add_component_v2 | ( | const component & | c | ) |

Add a sub-component, does not automatically create action rows. This should be used for components v2 where you do not want to add action rows automatically.

Parameters

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

  id | Default value. ID of a user, role, or channel
  type | The type this default value represents

## ◆ add_media_gallery_item()

component & dpp::component::add_media_gallery_item | ( | const component & | media_gallery_item | ) |

Add a media gallery item to a media gallery type (v2).

Parameters

  media_gallery_item | item to add

Returns

## ◆ add_select_option()

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

Add a select option.

Parameters

  option | option to add

Returns
  component& Reference to self

## ◆ build_json()

std::string dpp::json_interface< component >::build_json | ( | bool | with_id = false | ) | const

inline inherited

Convert object to json string.

Parameters

  with_id | Whether 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()

component & dpp::json_interface< component >::fill_from_json | ( | nlohmann::json * | j | ) |

inline inherited

Convert object from nlohmann::json.

Parameters

  j | nlohmann::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

  j | A json object to read from

Returns
  A reference to self

## ◆ set_accent()

component & dpp::component::set_accent | ( | uint32_t | accent_colour | ) |

Set accent colour for container type (v2).

Parameters

  accent_colour | Accent colour for container

Returns
  self

## ◆ set_accessory()

component & dpp::component::set_accessory | ( | const component & | accessory_component | ) |

Set accessory component for components which support it. Can be a button or a thumbnail image.

Parameters

  accessory_component | accessory component

Returns

## ◆ set_content()

component & dpp::component::set_content | ( | const std::string & | text | ) |

For text content types, set content.

Note
  Ignored for other types

Parameters

  text | text to set

Returns

## ◆ 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

  val | Value text to set. It will be truncated to the maximum length of 4000 UTF-8 characters.

Returns
  component& Reference to self

## ◆ set_description()

component & dpp::component::set_description | ( | const std::string & | text | ) |

For media types, set description.

Note
  Ignored for other types

Parameters

  text | text to set

Returns

## ◆ set_disabled()

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

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

Parameters

  disable | True to disable the component, False to enable the component.

Returns
  component& Reference to self

## ◆ set_divider()

component & dpp::component::set_divider | ( | bool | divider | ) |

Set divider visibility for separator type (v2).

Parameters

  divider | true to show a visible divider

Returns
  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

  name | Emoji name, or unicode character to use
  id | Emoji id, for custom emojis only.
  animated | True if the custom emoji is animated.

Returns
  component& Reference to self

## ◆ set_file()

component & dpp::component::set_file | ( | std::string_view | attachment_url | ) |

Set the attachment url for file type components. The format of the attachment url should be of the type "attachment://...".

Parameters

  attachment_url | url to attachment. Should have been attached via add_file().

Returns
  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

  id | Custom 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

  label | Label 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_l | max 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_values | max 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_l | min 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_values | min 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

  placeholder | placeholder 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

  require | True 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

  sku | The SKU ID

Returns
  component& reference to self

## ◆ set_spacing()

component & dpp::component::set_spacing | ( | separator_spacing | sep_spacing | ) |

Set separator spacing for separator type (v2).

Parameters

  sep_spacing | separator spacing, small or large

Returns
  self

## ◆ set_spoiler()

component & dpp::component::set_spoiler | ( | bool | spoiler_enable | ) |

For media and file component types, set spoiler status.

Note
  Ignored for other types

Parameters

  spoiler_enable | True to enable spoiler masking

Returns

## ◆ 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

  cs | Component 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

  ts | Text style type to set

Returns
  component& reference to self

## ◆ set_thumbnail()

component & dpp::component::set_thumbnail | ( | std::string_view | url | ) |

Set component thumbnail for thumbnail type (v2.

Parameters

  url | The embed thumbnail url (only supports http(s) and attachments)

Returns
  A reference to self so this method may be "chained".

## ◆ 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

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

  url | URL to set. It will be truncated to the maximum length of 512 UTF-8 characters.

Returns
  component& reference to self.

## ◆ to_json()

auto dpp::json_interface< component >::to_json | ( | bool | with_id = false | ) | const

inline inherited

Convert object to nlohmann::json.

Parameters

  with_id | Whether 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 Symbol Documentation

## ◆ json_interface< component >

friend struct json_interface< component >

friend

## Member Data Documentation

## ◆ accent

std::optional<uint32_t> dpp::component::accent

Accent colour for container types (v2).

## ◆ accessory

std::shared_ptr<component> dpp::component::accessory

accessory component for components which support it (v2) Can be a button or a thumbnail.

## ◆ 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.

## ◆ content

std::string dpp::component::content

Text content for section and text display types (v2).

## ◆ 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.

## ◆ description

std::string dpp::component::description

Description for media items (v2).

## ◆ disabled

bool dpp::component::disabled

Disabled flag (for buttons).

## ◆ emoji

partial_emoji dpp::component::emoji

The emoji for this component.

## ◆ file

std::optional<embed_image> dpp::component::file

Unfurled file URL for file objects (v2) Should be in the format "attachment://...".

## ◆ is_divider

bool dpp::component::is_divider

can be set for separator types (v2)

## ◆ 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.

## ◆ media_gallery_items

std::vector<std::shared_ptr<component> > dpp::component::media_gallery_items

Media gallery items for media galleries (v2).

## ◆ 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.

## ◆ spacing

separator_spacing dpp::component::spacing

Valid for separator types (v2).

## ◆ spoiler

bool dpp::component::spoiler

Spoiler state for media and file items.

## ◆ style

component_style dpp::component::style

Component style (for buttons).

## ◆ text_style

text_style_type dpp::component::text_style

Text style (for text inputs).

## ◆ thumbnail

std::optional<embed_image> dpp::component::thumbnail

Unfurled media for thumbnail objects (v2).

## ◆ 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.13 D++ Library version 9.0.12 D++ Library version 9.0.11 D++ Library version 9.0.10 D++ Library version 9.0.9 D++ Library version 9.0.8 D++ Library version 9.0.7 D++ Library version 9.0.6 D++ Library version 9.0.5 D++ Library version 9.0.4 D++ Library version 9.0.3 D++ Library version 9.0.2 D++ Library version 9.0.1 D++ Library version 9.0.0 D++ Library version 1.0.2 D++ Library version 1.0.1 D++ Library version 1.0.0