From 506e69addf81fc8cc542520d7db17937a8b74c5b Mon Sep 17 00:00:00 2001
From: guillempages <guillempages@users.noreply.github.com>
Date: Tue, 13 Aug 2024 09:44:43 +0200
Subject: [PATCH] [online_image] add option to show placeholder while
 downloading (#7083)

Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
---
 esphome/components/online_image/__init__.py      |  6 ++++++
 esphome/components/online_image/online_image.cpp |  8 ++++++++
 esphome/components/online_image/online_image.h   | 11 +++++++++++
 3 files changed, 25 insertions(+)

diff --git a/esphome/components/online_image/__init__.py b/esphome/components/online_image/__init__.py
index ee5357457a..d9a7609543 100644
--- a/esphome/components/online_image/__init__.py
+++ b/esphome/components/online_image/__init__.py
@@ -27,6 +27,7 @@ CODEOWNERS = ["@guillempages"]
 MULTI_CONF = True
 
 CONF_ON_DOWNLOAD_FINISHED = "on_download_finished"
+CONF_PLACEHOLDER = "placeholder"
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -73,6 +74,7 @@ ONLINE_IMAGE_SCHEMA = cv.Schema(
         #
         cv.Required(CONF_URL): cv.url,
         cv.Required(CONF_FORMAT): cv.enum(IMAGE_FORMAT, upper=True),
+        cv.Optional(CONF_PLACEHOLDER): cv.use_id(Image_),
         cv.Optional(CONF_BUFFER_SIZE, default=2048): cv.int_range(256, 65536),
         cv.Optional(CONF_ON_DOWNLOAD_FINISHED): automation.validate_automation(
             {
@@ -152,6 +154,10 @@ async def to_code(config):
 
     cg.add(var.set_transparency(transparent))
 
+    if placeholder_id := config.get(CONF_PLACEHOLDER):
+        placeholder = await cg.get_variable(placeholder_id)
+        cg.add(var.set_placeholder(placeholder))
+
     for conf in config.get(CONF_ON_DOWNLOAD_FINISHED, []):
         trigger = cg.new_Pvariable(conf[CONF_TRIGGER_ID], var)
         await automation.build_automation(trigger, [], conf)
diff --git a/esphome/components/online_image/online_image.cpp b/esphome/components/online_image/online_image.cpp
index a4cf0158aa..480bad6aca 100644
--- a/esphome/components/online_image/online_image.cpp
+++ b/esphome/components/online_image/online_image.cpp
@@ -35,6 +35,14 @@ OnlineImage::OnlineImage(const std::string &url, int width, int height, ImageFor
   this->set_url(url);
 }
 
+void OnlineImage::draw(int x, int y, display::Display *display, Color color_on, Color color_off) {
+  if (this->data_start_) {
+    Image::draw(x, y, display, color_on, color_off);
+  } else if (this->placeholder_) {
+    this->placeholder_->draw(x, y, display, color_on, color_off);
+  }
+}
+
 void OnlineImage::release() {
   if (this->buffer_) {
     ESP_LOGD(TAG, "Deallocating old buffer...");
diff --git a/esphome/components/online_image/online_image.h b/esphome/components/online_image/online_image.h
index 30e97760ea..775cc46e0b 100644
--- a/esphome/components/online_image/online_image.h
+++ b/esphome/components/online_image/online_image.h
@@ -50,6 +50,8 @@ class OnlineImage : public PollingComponent,
   OnlineImage(const std::string &url, int width, int height, ImageFormat format, image::ImageType type,
               uint32_t buffer_size);
 
+  void draw(int x, int y, display::Display *display, Color color_on, Color color_off) override;
+
   void update() override;
   void loop() override;
 
@@ -60,6 +62,14 @@ class OnlineImage : public PollingComponent,
     }
   }
 
+  /**
+   * @brief Set the image that needs to be shown as long as the downloaded image
+   *  is not available.
+   *
+   * @param placeholder Pointer to the (@link Image) to show as placeholder.
+   */
+  void set_placeholder(image::Image *placeholder) { this->placeholder_ = placeholder; }
+
   /**
    * Release the buffer storing the image. The image will need to be downloaded again
    * to be able to be displayed.
@@ -113,6 +123,7 @@ class OnlineImage : public PollingComponent,
   DownloadBuffer download_buffer_;
 
   const ImageFormat format_;
+  image::Image *placeholder_{nullptr};
 
   std::string url_{""};