From 807a9ecad717e46621a5214dbf849369d3afbc0b Mon Sep 17 00:00:00 2001
From: AnonymouX47 <anonymoux47@gmail.com>
Date: Tue, 21 Feb 2023 01:17:24 +0100
Subject: [PATCH] feat,refactor: Update `ITerm2Image.clear()`

- Add: *cursor* parameter to support clearing images intersecting with
  the cursor.
- Add: *now* parameter to determine when images should be cleared.
- Change: The escape sequence emmited to clear all images now deletes
  the images and image data.
---
 src/term_image/image/iterm2.py | 33 ++++++++++++++++++++++++++-------
 1 file changed, 26 insertions(+), 7 deletions(-)

diff --git a/src/term_image/image/iterm2.py b/src/term_image/image/iterm2.py
index ad3ba989..8e6bfba0 100644
--- a/src/term_image/image/iterm2.py
+++ b/src/term_image/image/iterm2.py
@@ -14,7 +14,15 @@
 import PIL
 
 from ..exceptions import TermImageWarning, _style_error
-from ..utils import CSI, ESC, OSC, ST, get_terminal_name_version, get_terminal_size
+from ..utils import (
+    CSI,
+    ESC,
+    OSC,
+    ST,
+    get_terminal_name_version,
+    get_terminal_size,
+    write_tty,
+)
 from .common import GraphicsImage, ImageSource
 
 # Constants for render methods
@@ -217,16 +225,26 @@ class ITerm2Image(GraphicsImage):
     _TERM_VERSION: str = ""
 
     @classmethod
-    def clear(cls) -> None:
-        """Clears all images on-screen.
+    def clear(cls, cursor: bool = False, now: bool = False) -> None:
+        """Clears images.
+
+        Args:
+            cursor: If ``True``, all images intersecting with the current cursor
+              position are cleared. Otherwise, all visible images are cleared.
+            now: If ``True`` the images are cleared immediately. Otherwise they're
+              cleared when next Python's standard output buffer is flushed.
 
         Required and works only on Konsole, as text doesn't overwrite images.
         """
-        # `is_supported()` is called first in case it has never been called
+        # There's no point checking for forced support since this is only required on
+        # konsole which supports the protocol.
+        # `is_supported()` is first called to ensure `_TERM` has been set.
         if cls.is_supported() and cls._TERM == "konsole":
-            # Seems Konsole utilizes the same image rendering implementation as it
+            # Konsole utilizes the same image rendering implementation as it
             # uses for the kiity graphics protocol.
-            _stdout_write(DELETE_ALL_IMAGES)
+            (write_tty if now else _stdout_write)(
+                DELETE_CURSOR_IMAGES if cursor else DELETE_ALL_IMAGES
+            )
 
     def draw(
         self,
@@ -592,6 +610,7 @@ def _render_image(
 
 
 START = f"{OSC}1337;File="
-DELETE_ALL_IMAGES = f"{ESC}_Ga=d;{ST}".encode()
+DELETE_ALL_IMAGES = f"{ESC}_Ga=d,d=A;{ST}".encode()
+DELETE_CURSOR_IMAGES = f"{ESC}_Ga=d,d=C;{ST}".encode()
 native_anim = Event()
 _stdout_write = sys.stdout.buffer.write