ESPHome 2026.11.0-dev
Loading...
Searching...
No Matches
esphome::select::Select Class Reference

Base-class for all selects. More...

#include <select.h>

Inheritance diagram for esphome::select::Select:
esphome::EntityBase esphome::airton::VerticalDirectionSelect esphome::copy::CopySelect esphome::demo::DemoSelect esphome::duco::DucoSelect esphome::es8388::ADCInputMicSelect esphome::es8388::DacOutputSelect esphome::espectre::TrafficModeSelect esphome::haier::HorizontalAirflowSelect esphome::haier::VerticalAirflowSelect esphome::homeassistant::HomeassistantSelect esphome::ld2410::BaudRateSelect esphome::ld2410::DistanceResolutionSelect esphome::ld2410::LightOutControlSelect esphome::ld2410s::LD2410SSelect esphome::ld2412::BaudRateSelect esphome::ld2412::DistanceResolutionSelect esphome::ld2412::LightOutControlSelect esphome::ld2420::LD2420Select esphome::ld2450::BaudRateSelect esphome::ld2450::ZoneTypeSelect esphome::ld6002b::LD6002BSelect esphome::logger::LoggerLevelSelect esphome::lvgl::LVGLSelect esphome::mitsubishi_cn105::MitsubishiCN105VerticalVaneDirectionSelect esphome::modbus_controller::ModbusSelect esphome::seeed_mr24hpc1::ExistenceBoundarySelect esphome::seeed_mr24hpc1::MotionBoundarySelect esphome::seeed_mr24hpc1::SceneModeSelect esphome::seeed_mr24hpc1::UnmanTimeSelect esphome::seeed_mr60fda2::HeightThresholdSelect esphome::seeed_mr60fda2::InstallHeightSelect esphome::seeed_mr60fda2::SensitivitySelect esphome::select::ApplySelect< Fn > esphome::template_::BaseTemplateSelect esphome::tuya::TuyaSelect

Public Member Functions

 Select ()=default
 
 ~Select ()=default
 
void publish_state (const std::string &state)
 
void publish_state (const char *state)
 
void publish_state (size_t index)
 
StringRef current_option () const
 Return the currently selected option, or empty StringRef if no state.
 
SelectCall make_call ()
 Instantiate a SelectCall object to modify this select component's state.
 
bool has_option (const std::string &option) const
 Return whether this select component contains the provided option.
 
bool has_option (const char *option) const
 
bool has_index (size_t index) const
 Return whether this select component contains the provided index offset.
 
size_t size () const
 Return the number of options in this select component.
 
optional< size_t > index_of (const char *option, size_t len) const
 Find the (optional) index offset of the provided option value.
 
optional< size_t > index_of (const std::string &option) const
 
optional< size_t > index_of (const char *option) const
 
optional< size_t > active_index () const
 Return the (optional) index offset of the currently active option.
 
optional< std::string > at (size_t index) const
 Return the (optional) option value at the provided index offset.
 
const char * option_at (size_t index) const
 Return the option value at the provided index offset (as const char* from flash).
 
template<typename F >
void add_on_state_callback (F &&callback)
 
- Public Member Functions inherited from esphome::EntityBase
 ESPDEPRECATED ("Use get_name_to() or get_log_name() instead. Will be removed in ESPHome 2027.5.0", "2026.11.0") const StringRef &get_name() const
 The name is in flash here; the first call makes a RAM copy that is kept for the life of the device.
 
StringRef get_name_to (std::span< char, ENTITY_NAME_BUF_SIZE > buffer) const
 Get the name of this Entity, copied out of flash into buffer.
 
 ESPDEPRECATED ("Use get_name_to() or get_log_name() instead. Will be removed in ESPHome 2027.5.0", "2026.11.0") const StringRef &get_name() const
 
const StringRef & get_name_to (std::span< char, ENTITY_NAME_BUF_SIZE >) const
 
bool name_equals (const StringRef &other) const
 
const ProgmemStringRef & get_name_progmem () const
 The name as stored, for consumers that read flash themselves (e.g. API progmem fields).
 
size_t write_name_to (char *buf, size_t buf_size) const
 Copy the name into buf (null terminated), returns its length.
 
const LogString * get_log_name () const
 Get the name for a "%s" log argument (LOG_STR_ARG).
 
bool has_own_name () const
 
uint32_t get_object_id_hash () const
 
StringRef get_object_id_to (std::span< char, OBJECT_ID_MAX_LEN > buf) const
 Get object_id with zero heap allocation For static case: returns StringRef to internal storage (buffer unused) For dynamic case: formats into buffer and returns StringRef to buffer.
 
size_t write_object_id_to (char *buf, size_t buf_size) const
 Write object_id directly to buffer, returns length written (excluding null) Useful for building compound strings without intermediate buffer.
 
bool is_internal () const
 
void set_internal (bool internal)
 
bool is_disabled_by_default () const
 
EntityCategory get_entity_category () const
 
const char * get_device_class_to (std::span< char, MAX_DEVICE_CLASS_LENGTH > buffer) const
 
ProgmemStringRef get_device_class_progmem () const
 The device class as stored (in flash on ESP8266), for consumers that read flash themselves.
 
StringRef get_unit_of_measurement_ref () const
 
const char * get_icon_to (std::span< char, MAX_ICON_LENGTH > buffer) const
 
ProgmemStringRef get_icon_progmem () const
 The icon as stored (in flash on ESP8266), for consumers that read flash themselves.
 
uint32_t get_device_id () const
 
Device * get_device () const
 
bool has_state () const
 
void set_has_state (bool state)
 
 ESPDEPRECATED ("Use make_entity_preference<T>() instead, or preferences won't be migrated. " "See https://github.com/esphome/backlog/issues/85. Will be removed in 2027.1.0.", "2026.7.0") uint32_t get_preference_hash()
 Get a unique hash for storing preferences/settings for this entity.
 
template<typename T >
ESPPreferenceObject make_entity_preference (uint32_t version=0)
 Create a preference object for storing this entity's state/settings.
 
template<typename T >
ESPPreferenceObject make_entity_preference (uint32_t version, bool in_flash)
 As make_entity_preference(), stored in flash or RTC memory where the backend supports the choice.
 

Data Fields

SelectTraits traits
 

Protected Member Functions

virtual void control (size_t index)
 Set the value of the select by index, this is an optional virtual method.
 
virtual void control (const std::string &value)
 Set the value of the select, this is a virtual method that each select integration can implement.
 
- Protected Member Functions inherited from esphome::EntityBase
friend void::setup ()
 
friend void::original_setup ()
 
void configure_entity_ (const char *name, uint32_t object_id_hash, uint32_t entity_fields)
 Combined entity setup from codegen: set name, object_id hash, entity string indices, and flags.
 
void set_device_ (Device *device)
 
ESPPreferenceObject make_entity_preference_ (size_t size, uint32_t version)
 Non-template helpers for make_entity_preference() to avoid code bloat.
 
ESPPreferenceObject make_entity_preference_ (size_t size, uint32_t version, bool in_flash)
 
uint32_t entity_preference_key_ (uint32_t version)
 Key for both helpers; preference hash migration goes here.
 

Protected Attributes

size_t active_index_ {0}
 
LazyCallbackManager< void(size_t)> state_callback_
 
- Protected Attributes inherited from esphome::EntityBase
ProgmemStringRef name_
 
uint32_t object_id_hash_ {}
 
Device * device_ {}
 
struct esphome::EntityBase::EntityFlags flags_
 
uint8_t device_class_idx_ {}
 
uint8_t uom_idx_ {}
 
uint8_t icon_idx_ {}
 

Detailed Description

Base-class for all selects.

A select can use publish_state to send out a new value.

Definition at line 28 of file select.h.

Constructor & Destructor Documentation

◆ Select()

esphome::select::Select::Select ( )
default

◆ ~Select()

esphome::select::Select::~Select ( )
default

Member Function Documentation

◆ active_index()

optional< size_t > esphome::select::Select::active_index ( ) const

Return the (optional) index offset of the currently active option.

Definition at line 45 of file select.cpp.

◆ add_on_state_callback()

template<typename F >
void esphome::select::Select::add_on_state_callback ( F && callback)
inline

Definition at line 73 of file select.h.

◆ at()

optional< std::string > esphome::select::Select::at ( size_t index) const

Return the (optional) option value at the provided index offset.

Definition at line 52 of file select.cpp.

◆ control() [1/2]

virtual void esphome::select::Select::control ( const std::string & value)
inlineprotectedvirtual

Set the value of the select, this is a virtual method that each select integration can implement.

IMPORTANT: At least ONE of the two control() methods must be overridden by derived classes. Overriding control(size_t) is PREFERRED as it avoids string conversions.

This method is called by control(size_t) when not overridden, or directly by external code. Default implementation converts to index and calls control(size_t).

Parameters
valueThe value as validated by the caller.

Definition at line 104 of file select.h.

◆ control() [2/2]

virtual void esphome::select::Select::control ( size_t index)
inlineprotectedvirtual

Set the value of the select by index, this is an optional virtual method.

IMPORTANT: At least ONE of the two control() methods must be overridden by derived classes. Overriding this index-based version is PREFERRED as it avoids string conversions.

This method is called by the SelectCall when the index is already known. Default implementation converts to string and calls control(const std::string&).

Parameters
indexThe index as validated by the SelectCall.

Reimplemented in esphome::airton::VerticalDirectionSelect, esphome::copy::CopySelect, esphome::demo::DemoSelect, esphome::duco::DucoSelect, esphome::es8388::ADCInputMicSelect, esphome::es8388::DacOutputSelect, esphome::espectre::TrafficModeSelect, esphome::haier::HorizontalAirflowSelect, esphome::haier::VerticalAirflowSelect, esphome::homeassistant::HomeassistantSelect, esphome::ld2410::BaudRateSelect, esphome::ld2410::DistanceResolutionSelect, esphome::ld2410::LightOutControlSelect, esphome::ld2410s::LD2410SSelect, esphome::ld2412::BaudRateSelect, esphome::ld2412::DistanceResolutionSelect, esphome::ld2412::LightOutControlSelect, esphome::ld2420::LD2420Select, esphome::ld2450::BaudRateSelect, esphome::ld2450::ZoneTypeSelect, esphome::ld6002b::LD6002BSelect, esphome::logger::LoggerLevelSelect, esphome::lvgl::LVGLSelect, esphome::mitsubishi_cn105::MitsubishiCN105VerticalVaneDirectionSelect, esphome::modbus_controller::ModbusSelect, esphome::seeed_mr24hpc1::ExistenceBoundarySelect, esphome::seeed_mr24hpc1::MotionBoundarySelect, esphome::seeed_mr24hpc1::SceneModeSelect, esphome::seeed_mr24hpc1::UnmanTimeSelect, esphome::seeed_mr60fda2::HeightThresholdSelect, esphome::seeed_mr60fda2::InstallHeightSelect, esphome::seeed_mr60fda2::SensitivitySelect, esphome::select::ApplySelect< Fn >, esphome::template_::TemplateSelect< HAS_LAMBDA, OPTIMISTIC, RESTORE_VALUE, INITIAL_OPTION_INDEX >, esphome::template_::TemplateSelectWithSetAction< HAS_LAMBDA, OPTIMISTIC, RESTORE_VALUE, INITIAL_OPTION_INDEX >, and esphome::tuya::TuyaSelect.

Definition at line 92 of file select.h.

◆ current_option()

StringRef esphome::select::Select::current_option ( ) const
inline

Return the currently selected option, or empty StringRef if no state.

The returned StringRef points to string literals from codegen (static storage). Traits are set once at startup and valid for the lifetime of the program.

Definition at line 42 of file select.h.

◆ has_index()

bool esphome::select::Select::has_index ( size_t index) const
inline

Return whether this select component contains the provided index offset.

Definition at line 54 of file select.h.

◆ has_option() [1/2]

bool esphome::select::Select::has_option ( const char * option) const
inline

Definition at line 51 of file select.h.

◆ has_option() [2/2]

bool esphome::select::Select::has_option ( const std::string & option) const
inline

Return whether this select component contains the provided option.

Definition at line 50 of file select.h.

◆ index_of() [1/3]

optional< size_t > esphome::select::Select::index_of ( const char * option) const
inline

Definition at line 62 of file select.h.

◆ index_of() [2/3]

optional< size_t > esphome::select::Select::index_of ( const char * option,
size_t len ) const

Find the (optional) index offset of the provided option value.

Definition at line 35 of file select.cpp.

◆ index_of() [3/3]

optional< size_t > esphome::select::Select::index_of ( const std::string & option) const
inline

Definition at line 61 of file select.h.

◆ make_call()

SelectCall esphome::select::Select::make_call ( )
inline

Instantiate a SelectCall object to modify this select component's state.

Definition at line 47 of file select.h.

◆ option_at()

const char * esphome::select::Select::option_at ( size_t index) const

Return the option value at the provided index offset (as const char* from flash).

Definition at line 60 of file select.cpp.

◆ publish_state() [1/3]

void esphome::select::Select::publish_state ( const char * state)

Definition at line 11 of file select.cpp.

◆ publish_state() [2/3]

void esphome::select::Select::publish_state ( const std::string & state)
inline

Definition at line 35 of file select.h.

◆ publish_state() [3/3]

void esphome::select::Select::publish_state ( size_t index)

Definition at line 20 of file select.cpp.

◆ size()

size_t esphome::select::Select::size ( ) const
inline

Return the number of options in this select component.

Definition at line 57 of file select.h.

Field Documentation

◆ active_index_

size_t esphome::select::Select::active_index_ {0}
protected

Definition at line 80 of file select.h.

◆ state_callback_

LazyCallbackManager<void(size_t)> esphome::select::Select::state_callback_
protected

Definition at line 111 of file select.h.

◆ traits

SelectTraits esphome::select::Select::traits

Definition at line 30 of file select.h.


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