egui_elements/widgets/

secure_text_edit.rs

use egui::{
   Align, Align2, Color32, CursorIcon, Event, EventFilter, FontId, FontSelection, Galley,
   IMEPurpose, Id, ImeEvent, Key, KeyboardShortcut, Margin, Modifiers, NumExt, Response, Sense,
   Shape, TextWrapMode, Ui, Vec2, Widget, WidgetInfo, WidgetText, epaint, output,
   text::{self, LayoutJob},
   text_selection::{self, CCursorRange, text_cursor_state::byte_index_from_char_index},
   vec2,
};

use crate::theme::Theme;
use crate::visuals::TextEditVisuals;
use std::{fmt::Debug, hash::Hash, sync::Arc};

#[cfg(feature = "secure-types")]
use secure_types::{SecureString, Zeroize};

/// Buffer used by [`SecureTextEdit`].
///
/// Implemented for [`String`] always, and for [`secure_types::SecureString`]
/// when the `secure-types` feature is on. Secure buffers report
/// [`TextBuffer::is_secure`] so the widget can avoid extra copies.
pub trait TextBuffer {
   /// `true` when the backing store should not be cloned into egui history.
   fn is_secure(&self) -> bool;
   /// Insert `text_to_insert` at the given char index. Returns chars written.
   fn insert_text_at_char_idx(&mut self, char_idx: usize, text_to_insert: &str) -> usize;
   /// Delete the half-open char range.
   fn delete_text_char_range(&mut self, char_range: core::ops::Range<usize>);
   /// Number of Unicode scalar values.
   fn char_len(&self) -> usize;
   /// Snapshot the contents. Prefer not calling this on a secure buffer.
   fn to_string(&self) -> String;
}

#[cfg(feature = "secure-types")]
impl TextBuffer for SecureString {
   fn is_secure(&self) -> bool {
      true
   }

   fn insert_text_at_char_idx(&mut self, char_idx: usize, text_to_insert: &str) -> usize {
      self.insert_text_at_char_idx(char_idx, text_to_insert)
   }

   fn delete_text_char_range(&mut self, char_range: core::ops::Range<usize>) {
      self.delete_text_char_range(char_range)
   }

   fn char_len(&self) -> usize {
      self.char_len()
   }

   fn to_string(&self) -> String {
      self.unlock_str(|s| s.to_string())
   }
}

impl TextBuffer for String {
   fn is_secure(&self) -> bool {
      false
   }

   fn insert_text_at_char_idx(&mut self, char_idx: usize, text_to_insert: &str) -> usize {
      let byte_idx = byte_index_from_char_index(self.as_str(), char_idx.into());
      self.insert_str(byte_idx.into(), text_to_insert);

      text_to_insert.chars().count()
   }

   fn delete_text_char_range(&mut self, char_range: core::ops::Range<usize>) {
      assert!(
         char_range.start <= char_range.end,
         "start must be <= end, but got {char_range:?}"
      );

      let byte_start = byte_index_from_char_index(self.as_str(), char_range.start.into());
      let byte_end = byte_index_from_char_index(self.as_str(), char_range.end.into());

      self.drain(byte_start.0..byte_end.0);
   }

   fn char_len(&self) -> usize {
      self.chars().count()
   }

   fn to_string(&self) -> String {
      self.to_owned()
   }
}

/// Persistent cursor / IME state for a [`SecureTextEdit`].
#[derive(Clone, Debug, Default)]
pub struct SecureTextEditState {
   /// Selection and cursor.
   pub cursor: text_selection::TextCursorState,
   /// Horizontal scroll offset for single-line fields.
   pub singleline_offset: f32,
   /// Seconds since start, last time the user interacted.
   pub last_interaction_time: f64,
   /// True while a non-empty IME preedit is in the buffer.
   ///
   /// Not tied to the deprecated `ImeEvent::Enabled`. Empty Preedit/Commit
   /// events (GNOME/ibus on Wayland) must be ignored when this is false,
   /// or the cursor jumps to index 0 and text is typed in reverse.
   pub ime_enabled: bool,
   /// Span of the current preedit, if any. Do not use this as the delete
   /// target — always mutate the live cursor range, like egui 0.36.
   pub ime_cursor_range: CCursorRange,
}

impl SecureTextEditState {
   /// Load persisted state for `id`, if any.
   pub fn load(ctx: &egui::Context, id: egui::Id) -> Option<Self> {
      ctx.data_mut(|d| d.get_persisted(id))
   }

   /// Persist this state under `id`.
   pub fn store(self, ctx: &egui::Context, id: egui::Id) {
      ctx.data_mut(|d| d.insert_persisted(id, self));
   }
}

/// Output of [`SecureTextEdit::show`].
pub struct SecureTextEditOutput {
   /// Interaction response of the field.
   pub response: Response,
   /// Updated cursor / IME state (already stored on the context).
   pub state: SecureTextEditState,
   /// Cursor range after this frame, if the field had focus.
   pub cursor_range: Option<CCursorRange>,
}

/// A widget for editing text.
///
/// This widget is identical to [`egui::TextEdit`], but it uses a custom [`TextBuffer`]
/// that can take either a [`SecureString`] or a [`String`].
///
/// To use it with a [`SecureString`], the feature `secure-types` must be enabled.
///
/// ## Notes
///
/// - Accessability like screen readers is disabled to avoid multiple unsecure allocations of the entered text.
/// - If you want to make sure the text you enter doesn't stay in memory in any way you have to set [`Self::password`] to `true`.
///
/// Otherwise egui will make copies of that text and some of the copied allocations will stay in memory.
#[must_use = "You should put this widget in a ui with `ui.add(widget);`"]
pub struct SecureTextEdit<'a> {
   text: &'a mut dyn TextBuffer,
   visuals: Option<TextEditVisuals>,
   hint_text: WidgetText,
   id: Option<Id>,
   id_salt: Option<Id>,
   font_selection: FontSelection,
   text_color: Option<Color32>,
   password: bool,
   frame: bool,
   margin: Margin,
   multiline: bool,
   interactive: bool,
   desired_width: Option<f32>,
   desired_height_rows: usize,
   event_filter: EventFilter,
   cursor_at_end: bool,
   min_size: Vec2,
   align: Align2,
   clip_text: bool,
   char_limit: usize,
   return_key: Option<KeyboardShortcut>,
   background_color: Option<Color32>,
}

impl<'a> SecureTextEdit<'a> {
   /// Single-line field. Enter is consumed (see [`Self::return_key`]).
   pub fn singleline(text: &'a mut dyn TextBuffer) -> Self {
      Self {
         text,
         visuals: None,
         hint_text: Default::default(),
         id: None,
         id_salt: None,
         font_selection: FontSelection::default(),
         text_color: None,
         password: false,
         frame: true,
         margin: Margin::symmetric(4, 2),
         multiline: false,
         interactive: true,
         desired_width: None,
         desired_height_rows: 1,
         event_filter: EventFilter {
            horizontal_arrows: true,
            vertical_arrows: true,
            tab: false,
            ..Default::default()
         },
         cursor_at_end: true,
         min_size: Vec2::ZERO,
         align: Align2::LEFT_CENTER,
         clip_text: true,
         char_limit: usize::MAX,
         return_key: Some(KeyboardShortcut::new(Modifiers::NONE, Key::Enter)),
         background_color: None,
      }
   }

   /// Multi-line field. Text wraps; Enter inserts a newline by default.
   pub fn multiline(text: &'a mut dyn TextBuffer) -> Self {
      Self {
         text,
         visuals: None,
         hint_text: Default::default(),
         id: None,
         id_salt: None,
         font_selection: FontSelection::default(),
         text_color: None,
         password: false,
         frame: true,
         margin: Margin::symmetric(4, 2),
         multiline: true,
         interactive: true,
         desired_width: None,
         desired_height_rows: 4,
         event_filter: EventFilter {
            horizontal_arrows: true,
            vertical_arrows: true,
            tab: false,
            ..Default::default()
         },
         cursor_at_end: true,
         min_size: Vec2::ZERO,
         align: Align2::LEFT_TOP,
         clip_text: false,
         char_limit: usize::MAX,
         return_key: Some(KeyboardShortcut::new(Modifiers::NONE, Key::Enter)),
         background_color: None,
      }
   }

   /// Override the chrome that would otherwise come from the installed theme.
   pub fn visuals(mut self, visuals: TextEditVisuals) -> Self {
      self.visuals = Some(visuals);
      self
   }

   /// Force a widget id (otherwise derived from the `Ui` id + salt).
   pub fn id(mut self, id: Id) -> Self {
      self.id = Some(id);
      self
   }

   /// Alias for [`Self::id_salt`].
   pub fn id_source(self, id_source: impl Hash + Debug) -> Self {
      self.id_salt(id_source)
   }

   /// Extra id salt so two fields in the same `Ui` do not share state.
   pub fn id_salt(mut self, id_salt: impl Hash + Debug) -> Self {
      self.id_salt = Some(Id::new(id_salt));
      self
   }

   /// Placeholder shown when the buffer is empty.
   pub fn hint_text(mut self, hint_text: impl Into<WidgetText>) -> Self {
      self.hint_text = hint_text.into();
      self
   }

   /// Font used to lay out the text.
   pub fn font(mut self, font_selection: impl Into<FontSelection>) -> Self {
      self.font_selection = font_selection.into();
      self
   }

   /// Override the text color.
   pub fn text_color(mut self, text_color: Color32) -> Self {
      self.text_color = Some(text_color);
      self
   }

   /// Optional text color. `None` keeps the theme / style default.
   pub fn text_color_opt(mut self, text_color: Option<Color32>) -> Self {
      self.text_color = text_color;
      self
   }

   /// Mask glyphs and skip extra copies of the buffer.
   ///
   /// Required if you want the entered text not to linger in egui allocations.
   pub fn password(mut self, password: bool) -> Self {
      self.password = password;
      self
   }

   /// Draw the framed background. Default: `true`.
   pub fn frame(mut self, frame: bool) -> Self {
      self.frame = frame;
      self
   }

   /// Inner margin around the text.
   pub fn margin(mut self, margin: impl Into<Margin>) -> Self {
      self.margin = margin.into();
      self
   }

   /// If `false`, the field is painted but ignores input.
   pub fn interactive(mut self, interactive: bool) -> Self {
      self.interactive = interactive;
      self
   }

   /// Preferred width. Defaults to [`egui::Spacing::text_edit_width`].
   pub fn desired_width(mut self, desired_width: f32) -> Self {
      self.desired_width = Some(desired_width);
      self
   }

   /// Preferred height, in rows of text (multiline).
   pub fn desired_rows(mut self, desired_height_rows: usize) -> Self {
      self.desired_height_rows = desired_height_rows;
      self
   }

   /// If `true`, Tab inserts a tab instead of moving focus.
   pub fn lock_focus(mut self, tab_will_indent: bool) -> Self {
      self.event_filter.tab = tab_will_indent;
      self
   }

   /// Place the cursor at the end when the field first gains focus.
   pub fn cursor_at_end(mut self, b: bool) -> Self {
      self.cursor_at_end = b;
      self
   }

   /// Minimum allocated size.
   pub fn min_size(mut self, min_size: Vec2) -> Self {
      self.min_size = min_size;
      self
   }

   /// Horizontal alignment of the text inside the field.
   pub fn horizontal_align(mut self, align: Align) -> Self {
      self.align.0[0] = align;
      self
   }

   /// Vertical alignment of the text inside the field.
   pub fn vertical_align(mut self, align: Align) -> Self {
      self.align.0[1] = align;
      self
   }

   /// Clip overflowing text in single-line mode. Ignored for multiline.
   pub fn clip_text(mut self, b: bool) -> Self {
      if !self.multiline {
         self.clip_text = b;
      }
      self
   }

   /// Maximum number of characters accepted.
   pub fn char_limit(mut self, limit: usize) -> Self {
      self.char_limit = limit;
      self
   }

   /// Key that finishes editing on a single-line field. `None` disables it.
   pub fn return_key(mut self, return_key: impl Into<Option<KeyboardShortcut>>) -> Self {
      self.return_key = return_key.into();
      self
   }

   /// Override the background fill.
   pub fn background_color(mut self, color: Color32) -> Self {
      self.background_color = Some(color);
      self
   }

   /// Paint the field and return the response plus updated cursor state.
   pub fn show(mut self, ui: &mut Ui) -> SecureTextEditOutput {
      self.visuals = self.visuals.or_else(|| Theme::text_edit_visuals_from_ctx(ui.ctx()));
      let frame = self.frame;
      let where_to_put_background = ui.painter().add(Shape::Noop);
      let background_color =
         self.visuals.as_ref().map(|v| v.bg).unwrap_or(ui.visuals().extreme_bg_color);
      let is_interactive = self.interactive;

      let (output, text_edit_visuals) = self.show_content(ui);

      let outer_rect_for_frame = output.response.rect;
      if frame {
         let visuals = ui.style().interact(&output.response);
         let frame_rect = outer_rect_for_frame.expand(visuals.expansion);
         let corner = text_edit_visuals
            .as_ref()
            .map(|v| v.corner_radius)
            .unwrap_or(visuals.corner_radius);

         let shape = if is_interactive {
            if output.response.has_focus() || output.response.hovered() {
               let border =
                  text_edit_visuals.as_ref().map(|v| v.border_open).unwrap_or(visuals.bg_stroke);
               epaint::RectShape::new(
                  frame_rect,
                  corner,
                  background_color,
                  border,
                  epaint::StrokeKind::Inside,
               )
            } else {
               let border =
                  text_edit_visuals.as_ref().map(|v| v.border).unwrap_or(visuals.bg_stroke);
               epaint::RectShape::new(
                  frame_rect,
                  corner,
                  background_color,
                  border,
                  epaint::StrokeKind::Inside,
               )
            }
         } else {
            // Not interactive
            let visuals = &ui.style().visuals.widgets.inactive;
            let border = text_edit_visuals.as_ref().map(|v| v.border).unwrap_or(visuals.bg_stroke);
            epaint::RectShape::stroke(
               frame_rect,
               corner,
               border,
               epaint::StrokeKind::Inside,
            )
         };
         ui.painter().set(where_to_put_background, shape);
      }
      output
   }

   #[allow(clippy::too_many_lines)]
   fn show_content(mut self, ui: &mut Ui) -> (SecureTextEditOutput, Option<TextEditVisuals>) {
      let font_id = self.font_selection.resolve(ui.style());
      let text_color = ui
         .visuals()
         .override_text_color
         .unwrap_or_else(|| ui.visuals().widgets.inactive.text_color());

      let text_color = self.visuals.map(|v| v.text).unwrap_or(text_color);

      let row_height = ui.fonts_mut(|f| f.row_height(&font_id));
      let available_width = (ui.available_width() - self.margin.sum().x).at_least(24.0); // Min width
      let desired_width = self.desired_width.unwrap_or_else(|| ui.spacing().text_edit_width);
      let wrap_width = if ui.layout().horizontal_justify() {
         available_width
      } else {
         desired_width.min(available_width)
      };

      // --- Layout Galley ---

      let display_text_cow = if self.password {
         // Generate '●' string based on actual char count
         std::borrow::Cow::<'_, str>::Owned(
            std::iter::repeat(epaint::text::PASSWORD_REPLACEMENT_CHAR)
               .take(self.text.char_len())
               .collect::<String>(),
         )
      } else {
         std::borrow::Cow::Owned(self.text.to_string()) // !
      };

      let mut job = if self.multiline {
         LayoutJob::simple(
            (*display_text_cow).to_owned(),
            font_id.clone(),
            text_color,
            wrap_width,
         )
      } else {
         LayoutJob::simple_singleline(
            (*display_text_cow).to_owned(),
            font_id.clone(),
            text_color,
         )
      };

      job.halign = self.align.0[0];
      let mut galley: Arc<Galley> = ui.fonts_mut(|f| f.layout_job(job));

      // --- Size & Allocation ---
      let desired_inner_width = if self.clip_text && !self.multiline {
         wrap_width
      } else {
         galley.size().x.max(wrap_width)
      };
      let desired_height = (self.desired_height_rows.at_least(1) as f32) * row_height;
      let desired_inner_size = vec2(
         desired_inner_width,
         galley.size().y.max(desired_height),
      );
      let desired_outer_size = (desired_inner_size + self.margin.sum()).at_least(self.min_size);

      let (auto_id, outer_rect) = ui.allocate_space(desired_outer_size);
      let text_draw_rect = outer_rect - self.margin;

      let id = self.id.unwrap_or_else(|| {
         if let Some(id_salt) = self.id_salt {
            ui.make_persistent_id(id_salt)
         } else {
            auto_id
         }
      });
      let mut state = SecureTextEditState::load(ui.ctx(), id).unwrap_or_default();

      // --- Interaction ---
      let allow_drag_to_select =
         ui.input(|i| !i.has_touch_screen()) || ui.memory(|mem| mem.has_focus(id));
      let sense_behavior = if self.interactive {
         if allow_drag_to_select {
            Sense::click_and_drag()
         } else {
            Sense::click()
         }
      } else {
         Sense::hover()
      };
      let mut response = ui.interact(outer_rect, id, sense_behavior);
      response.set_intrinsic_size(vec2(desired_width, desired_outer_size.y));

      // Handle click to focus
      if self.interactive {
         if let Some(pointer_pos) = ui.ctx().pointer_interact_pos() {
            if response.hovered() {
               ui.output_mut(|o| o.mutable_text_under_cursor = true);
            }
            let singleline_offset_vec = vec2(state.singleline_offset, 0.0);
            let cursor_at_pointer =
               galley.cursor_from_pos(pointer_pos - text_draw_rect.min + singleline_offset_vec);

            let is_being_dragged = ui.ctx().is_being_dragged(response.id);
            let did_interact_with_cursor = state.cursor.pointer_interaction(
               ui,
               &response,
               cursor_at_pointer,
               &galley,
               is_being_dragged,
            );

            if did_interact_with_cursor || response.clicked() {
               ui.memory_mut(|mem| mem.request_focus(response.id));
               state.last_interaction_time = ui.input(|i| i.time);
            }
         }
      }
      if self.interactive && response.hovered() {
         ui.ctx().set_cursor_icon(CursorIcon::Text);
      }

      // --- Event Handling ---
      let mut cursor_range_after_events = None;
      let owns_ime_events = ui.memory(|mem| mem.owns_ime_events(id));
      if !owns_ime_events {
         state.ime_enabled = false;
         if let Some(range) = state.cursor.char_range() {
            state.cursor.set_char_range(Some(CCursorRange::one(range.primary)));
         }
      }

      if self.interactive && ui.memory(|mem| mem.has_focus(id)) {
         ui.memory_mut(|mem| mem.set_focus_lock_filter(id, self.event_filter));

         let default_cursor_range = if self.cursor_at_end {
            CCursorRange::one(galley.end())
         } else {
            CCursorRange::default()
         };

         let (text_changed_by_event, new_cursor_range, updated_galley) = secure_text_edit_events(
            ui,
            &mut state,
            self.text,
            &galley,
            id,
            self.multiline,
            self.password,
            default_cursor_range,
            owns_ime_events,
            self.char_limit,
            self.event_filter,
            self.return_key,
            &font_id,
            text_color,
            wrap_width,
            self.align.0[0],
         );

         if text_changed_by_event {
            response.mark_changed();
            galley = updated_galley;
         }
         cursor_range_after_events = Some(new_cursor_range);
         state.cursor.set_char_range(Some(new_cursor_range));
      }

      // --- Galley Positioning & Single-line Offset ---
      let mut galley_pos = self.align.align_size_within_rect(galley.size(), text_draw_rect).min;
      if self.clip_text && !self.multiline {
         let current_cursor_primary_x =
            match cursor_range_after_events.or_else(|| state.cursor.range(&galley)) {
               Some(cr) => galley.pos_from_cursor(cr.primary).min.x,
               None => 0.0,
            };
         let visible_width = text_draw_rect.width();
         let mut offset_x = state.singleline_offset;
         let visible_range_start = offset_x;
         let visible_range_end = offset_x + visible_width;

         if current_cursor_primary_x < visible_range_start {
            offset_x = current_cursor_primary_x;
         } else if current_cursor_primary_x > visible_range_end {
            offset_x = current_cursor_primary_x - visible_width;
         }
         offset_x = offset_x.at_most(galley.size().x - visible_width).at_least(0.0);
         state.singleline_offset = offset_x;
         galley_pos.x -= offset_x;
      } else {
         // For multiline or non-clip singleline, capture any alignment offset
         // state.singleline_offset = text_draw_rect.left() - galley_pos.x;
         state.singleline_offset = 0.0;
         // And ensure galley_pos respects it if it was aligned (e.g. center/right)
         state.singleline_offset = text_draw_rect.left() - galley_pos.x;
      }

      // --- Painting ---
      if ui.is_rect_visible(text_draw_rect) {
         let is_text_empty = self.text.char_len() == 0;
         if is_text_empty && !self.hint_text.is_empty() {
            let hint_text_color = ui.visuals().weak_text_color();
            let hint_font_id = FontSelection::default();
            let hint_galley = self.hint_text.clone().into_galley(
               ui,
               Some(TextWrapMode::Wrap),
               text_draw_rect.width(),
               hint_font_id,
            );
            let hint_galley_pos =
               self.align.align_size_within_rect(hint_galley.size(), text_draw_rect).min;
            ui.painter_at(text_draw_rect)
               .galley(hint_galley_pos, hint_galley, hint_text_color);
         }

         let mut galley_for_paint = galley.clone();
         if ui.memory(|mem| mem.has_focus(id)) {
            if let Some(cursor_range_for_sel) = state.cursor.range(&galley_for_paint) {
               text_selection::visuals::paint_text_selection(
                  &mut galley_for_paint,
                  ui.visuals(),
                  &cursor_range_for_sel,
                  None,
               );
            }
         }
         ui.painter_at(text_draw_rect).galley(galley_pos, galley_for_paint, text_color);

         // Paint cursor
         if self.interactive && ui.memory(|mem| mem.has_focus(id)) {
            if let Some(cursor_range_for_cursor_paint) = state.cursor.range(&galley) {
               // Use original galley for metrics
               let primary_cursor_rect_ui = text_selection::text_cursor_state::cursor_rect(
                  &galley,
                  &cursor_range_for_cursor_paint.primary,
                  row_height,
               )
               .translate(galley_pos.to_vec2());

               if response.changed() {
                  // Could also check selection_changed
                  ui.scroll_to_rect(
                     primary_cursor_rect_ui.expand(self.margin.sum().y / 2.0),
                     None,
                  );
               }

               if ui.ctx().input(|i| i.focused) {
                  // Viewport has focus
                  let time_since_last_interaction =
                     ui.input(|i| i.time) - state.last_interaction_time;
                  text_selection::visuals::paint_text_cursor(
                     ui,
                     &ui.painter_at(text_draw_rect.expand(1.0)), // Expand for cursor
                     primary_cursor_rect_ui,
                     time_since_last_interaction,
                  );
               }
               // IME output
               let to_global =
                  ui.ctx().layer_transform_to_global(ui.layer_id()).unwrap_or_default();
               ui.ctx().output_mut(|o| {
                  o.ime = Some(output::IMEOutput {
                     purpose: if self.password {
                        IMEPurpose::Password
                     } else {
                        IMEPurpose::Normal
                     },
                     rect: to_global * text_draw_rect,
                     cursor_rect: to_global * primary_cursor_rect_ui,
                     should_interrupt_composition: false,
                  });
               });
            }
         }
      }

      state.clone().store(ui.ctx(), id);

      // !
      // This is only for accessibility, so set them to empty is fine
      /*
      let _ = self.text.str_scope(|s| {
         if self.password {
            std::iter::repeat(epaint::text::PASSWORD_REPLACEMENT_CHAR)
               .take(s.chars().count())
               .collect()
         } else {
            s.to_string()
         }
      });
      */
      response.widget_info(|| {
         WidgetInfo::text_edit(
            ui.is_enabled(),
            String::new(),
            String::new(),
            String::new(),
         )
      });

      let output = SecureTextEditOutput {
         response,
         state,
         cursor_range: cursor_range_after_events,
      };

      let visuals = self.visuals.take();
      (output, visuals)
   }
}

impl<'a> Widget for SecureTextEdit<'a> {
   fn ui(self, ui: &mut Ui) -> Response {
      self.show(ui).response
   }
}

#[allow(clippy::too_many_arguments, clippy::fn_params_excessive_bools)]
fn secure_text_edit_events(
   ui: &Ui,
   state: &mut SecureTextEditState,
   text: &mut dyn TextBuffer,
   initial_galley: &Arc<Galley>,
   id: Id,
   multiline: bool,
   password: bool,
   default_cursor_range: CCursorRange,
   owns_ime_events: bool,
   char_limit: usize,
   event_filter: EventFilter,
   return_key: Option<KeyboardShortcut>,
   font_id: &FontId,
   text_color: Color32,
   wrap_width: f32,
   text_align_horizontal: Align,
) -> (bool, CCursorRange, Arc<Galley>) {
   let os = ui.ctx().os();
   let mut current_galley = initial_galley.clone();
   let mut cursor_range = state.cursor.range(&current_galley).unwrap_or(default_cursor_range);
   let mut text_changed_in_total = false;

   let events_filtered = ui.input(|i| i.filtered_events(&event_filter));

   for event in events_filtered {
      let current_char_len_before_event = text.char_len();
      let mut text_mutated_this_event = false;

      // Pass current_galley to on_event. If it modifies cursor_range, it uses current_galley.
      if cursor_range.on_event(os, &event, &current_galley, id) {
         state.last_interaction_time = ui.input(|i| i.time);
         continue;
      }

      let new_ccursor_range_opt: Option<CCursorRange> = match event {
         // For now don't allow copy/cut on any text
         Event::Copy => None,
         Event::Cut => None,
         #[cfg_attr(not(feature = "secure-types"), allow(unused_mut))]
         Event::Paste(mut text_to_paste) => {
            if !text_to_paste.is_empty() {
               let [min, max] = cursor_range.sorted_cursors();
               let selection_char_len = max.index - min.index;
               text.delete_text_char_range(min.index.0..max.index.0);

               let space_available = char_limit.saturating_sub(
                  current_char_len_before_event.saturating_sub(selection_char_len.0),
               );
               let mut final_text_to_paste = if text_to_paste.chars().count() > space_available {
                  text_to_paste.chars().take(space_available).collect::<String>()
               } else {
                  text_to_paste.clone()
               };

               let mut current_ccursor = min;
               let chars_inserted =
                  text.insert_text_at_char_idx(current_ccursor.index.0, &final_text_to_paste);
               current_ccursor.index += chars_inserted;
               text_mutated_this_event = true; // Mark mutation

               #[cfg(feature = "secure-types")]
               {
                  text_to_paste.zeroize();
                  final_text_to_paste.zeroize();
               }

               Some(text::CCursorRange::one(current_ccursor))
            } else {
               None
            }
         }
         #[cfg_attr(not(feature = "secure-types"), allow(unused_mut))]
         Event::Text(mut text_to_insert) => {
            if !text_to_insert.is_empty() && text_to_insert != "\n" && text_to_insert != "\r" {
               let [min, max] = cursor_range.sorted_cursors();
               let selection_char_len = max.index - min.index;
               text.delete_text_char_range(min.index.0..max.index.0);

               let space_available = char_limit.saturating_sub(
                  current_char_len_before_event.saturating_sub(selection_char_len.0),
               );
               let mut final_text_to_insert = if text_to_insert.chars().count() > space_available {
                  text_to_insert.chars().take(space_available).collect::<String>()
               } else {
                  text_to_insert.clone()
               };

               let mut current_ccursor = min;
               let chars_inserted =
                  text.insert_text_at_char_idx(current_ccursor.index.0, &final_text_to_insert);
               current_ccursor.index += chars_inserted;
               text_mutated_this_event = true;

               #[cfg(feature = "secure-types")]
               {
                  text_to_insert.zeroize();
                  final_text_to_insert.zeroize();
               }
               Some(text::CCursorRange::one(current_ccursor))
            } else {
               None
            }
         }
         Event::Key {
            key: Key::Enter,
            pressed: true,
            modifiers,
            ..
         } if return_key.is_some_and(|rk| {
            Key::Enter == rk.logical_key && modifiers.matches_logically(rk.modifiers)
         }) =>
         {
            if multiline {
               let [min, max] = cursor_range.sorted_cursors();
               let selection_char_len = max.index - min.index;
               text.delete_text_char_range(min.index.0..max.index.0);

               let current_len_after_delete =
                  current_char_len_before_event.saturating_sub(selection_char_len.0);
               let space_available = char_limit.saturating_sub(current_len_after_delete);

               if space_available > 0 {
                  let mut current_ccursor = min;
                  let chars_inserted = text.insert_text_at_char_idx(current_ccursor.index.0, "\n");
                  current_ccursor.index += chars_inserted;
                  text_mutated_this_event = true; // Mark mutation
                  Some(text::CCursorRange::one(current_ccursor))
               } else {
                  None
               }
            } else {
               ui.memory_mut(|mem| mem.surrender_focus(id));
               None
            }
         }
         Event::Key {
            key: Key::Backspace,
            pressed: true,
            ..
         } => {
            // Modifiers for word/para delete later
            let [min, max] = cursor_range.sorted_cursors();
            let mut new_cursor_idx = min.index;
            if min == max {
               // No selection
               if min.index.0 > 0 {
                  text.delete_text_char_range(min.index.0 - 1..min.index.0);
                  new_cursor_idx = min.index - 1;
                  text_mutated_this_event = true;
               }
            } else {
               // Selection exists
               text.delete_text_char_range(min.index.0..max.index.0);
               // new_cursor_idx is already min.ccursor.index
               text_mutated_this_event = true;
            }
            if text_mutated_this_event {
               Some(text::CCursorRange::one(text::CCursor::new(
                  new_cursor_idx,
               )))
            } else {
               None
            }
         }
         Event::Key {
            key: Key::Delete,
            pressed: true,
            ..
         } => {
            // Modifiers for word/para delete later
            let [min, max] = cursor_range.sorted_cursors();
            if min == max {
               if min.index < current_char_len_before_event.into() {
                  // Before deleting
                  text.delete_text_char_range(min.index.0..min.index.0 + 1);
                  text_mutated_this_event = true;
               }
            } else {
               text.delete_text_char_range(min.index.0..max.index.0);
               text_mutated_this_event = true;
            }
            if text_mutated_this_event {
               Some(text::CCursorRange::one(min))
            } else {
               None
            }
         }
         Event::Key {
            key: Key::Tab,
            pressed: true,
            modifiers,
            ..
         } if multiline && event_filter.tab => {
            let [min, _max] = cursor_range.sorted_cursors();
            let mut current_ccursor = min;
            if modifiers.shift {
            } else {
               let space_available = char_limit.saturating_sub(current_char_len_before_event);
               if space_available > 0 {
                  // Enough for at least '\t'
                  let chars_inserted = text.insert_text_at_char_idx(current_ccursor.index.0, "\t");
                  current_ccursor.index += chars_inserted;
                  text_mutated_this_event = true;
               }
            }
            if text_mutated_this_event {
               Some(text::CCursorRange::one(current_ccursor))
            } else {
               None
            }
         }
         Event::Ime(ime_event) if owns_ime_events => {
            // GNOME 48+ / ibus on Wayland
            // emits empty Preedit/Commit around Latin keystrokes; those must not
            // rewrite the cursor using a stale composition range (that typed
            // backwards). Operate on the live cursor_range, and ignore empty
            // Preedit/Commit when no composition is active.
            match ime_event {
               #[allow(deprecated)]
               ImeEvent::Enabled | ImeEvent::Disabled => None,
               ImeEvent::Preedit {
                  text: ref composition_text,
                  ..
               }
               | ImeEvent::Commit(ref composition_text)
                  if composition_text.is_empty() && !state.ime_enabled =>
               {
                  None
               }
               ImeEvent::Preedit {
                  text: ref composition_text,
                  ..
               }
               | ImeEvent::Commit(ref composition_text)
                  if composition_text == "\n" || composition_text == "\r" =>
               {
                  None
               }
               #[cfg_attr(not(feature = "secure-types"), allow(unused_mut))]
               ImeEvent::Preedit {
                  text: mut preedit_text,
                  active_range_chars: _,
               } => {
                  let [min, max] = cursor_range.sorted_cursors();
                  text.delete_text_char_range(min.index.0..max.index.0);
                  let mut c = min;

                  if preedit_text.is_empty() {
                     state.ime_enabled = false;
                     text_mutated_this_event = true;
                     Some(text::CCursorRange::one(c))
                  } else {
                     let space_available = char_limit.saturating_sub(text.char_len());
                     let mut final_text = if preedit_text.chars().count() > space_available {
                        preedit_text.chars().take(space_available).collect::<String>()
                     } else {
                        preedit_text.clone()
                     };
                     let inserted = text.insert_text_at_char_idx(c.index.0, &final_text);
                     c.index += inserted;
                     state.ime_enabled = true;
                     state.ime_cursor_range = text::CCursorRange::two(min, c);
                     text_mutated_this_event = true;

                     #[cfg(feature = "secure-types")]
                     {
                        preedit_text.zeroize();
                        final_text.zeroize();
                     }

                     Some(text::CCursorRange::two(min, c))
                  }
               }
               #[cfg_attr(not(feature = "secure-types"), allow(unused_mut))]
               ImeEvent::Commit(mut commit_text) => {
                  state.ime_enabled = false;
                  let [min, max] = cursor_range.sorted_cursors();
                  text.delete_text_char_range(min.index.0..max.index.0);
                  let mut c = min;

                  if !commit_text.is_empty() {
                     let space_available = char_limit.saturating_sub(text.char_len());
                     let mut final_text = if commit_text.chars().count() > space_available {
                        commit_text.chars().take(space_available).collect::<String>()
                     } else {
                        commit_text.clone()
                     };
                     let inserted = text.insert_text_at_char_idx(c.index.0, &final_text);
                     c.index += inserted;

                     #[cfg(feature = "secure-types")]
                     final_text.zeroize();
                  }
                  text_mutated_this_event = true;

                  #[cfg(feature = "secure-types")]
                  commit_text.zeroize();

                  Some(text::CCursorRange::one(c))
               }
               ImeEvent::DeleteSurrounding {
                  before_chars,
                  after_chars,
               } => {
                  let [min, max] = cursor_range.sorted_cursors();
                  let mut new_range = cursor_range;
                  let mut mutated = false;

                  if after_chars > 0 {
                     let end = (max.index.0 + after_chars).min(text.char_len());
                     if end > max.index.0 {
                        text.delete_text_char_range(max.index.0..end);
                        mutated = true;
                     }
                  }
                  if before_chars > 0 {
                     let start = min.index.0.saturating_sub(before_chars);
                     if start < min.index.0 {
                        let deleted = min.index.0 - start;
                        text.delete_text_char_range(start..min.index.0);
                        new_range.primary.index =
                           (new_range.primary.index.0.saturating_sub(deleted)).into();
                        new_range.secondary.index =
                           (new_range.secondary.index.0.saturating_sub(deleted)).into();
                        mutated = true;
                     }
                  }

                  if mutated {
                     text_mutated_this_event = true;
                     Some(new_range)
                  } else {
                     None
                  }
               }
            }
         }
         _ => None,
      };

      if text_mutated_this_event {
         text_changed_in_total = true;

         // --- Re-layout galley ---

         let display_text_for_layout = if password {
            std::iter::repeat(epaint::text::PASSWORD_REPLACEMENT_CHAR)
               .take(text.char_len())
               .collect::<String>()
         } else {
            text.to_string() // !
         };

         let mut job = if multiline {
            LayoutJob::simple(
               display_text_for_layout,
               font_id.clone(),
               text_color,
               wrap_width,
            )
         } else {
            LayoutJob::simple_singleline(
               display_text_for_layout,
               font_id.clone(),
               text_color,
            )
         };

         job.halign = text_align_horizontal;
         current_galley = ui.fonts_mut(|f| f.layout_job(job));
      }

      if let Some(new_range) = new_ccursor_range_opt {
         state.last_interaction_time = ui.input(|i| i.time);
         cursor_range = new_range;
      }
      state.cursor.set_char_range(Some(cursor_range));
   }

   (
      text_changed_in_total,
      cursor_range,
      current_galley,
   )
}

#[cfg(test)]
mod tests {
   use super::*;
   use egui::{Context, Event, Id, ImeEvent, RawInput};

   fn run_pass(ctx: &Context, text: &mut String, id: Id, events: Vec<Event>) {
      let output = ctx.run_ui(
         RawInput {
            events,
            ..Default::default()
         },
         |ui| {
            ui.ctx().memory_mut(|mem| mem.request_focus(id));
            ui.add(SecureTextEdit::singleline(text).id(id));
         },
      );
      output.drop_without_applying_deltas();
   }

   fn ime_preedit(text: &str) -> Event {
      Event::Ime(ImeEvent::Preedit {
         text: text.to_owned(),
         active_range_chars: None,
      })
   }

   fn ime_commit(text: &str) -> Event {
      Event::Ime(ImeEvent::Commit(text.to_owned()))
   }

   /// GNOME 48+ / ibus on Wayland emits this sequence per Latin keystroke.
   fn gnome_wayland_keystroke(ch: char) -> Vec<Event> {
      let s = ch.to_string();
      vec![ime_preedit(&s), ime_commit(&s), ime_preedit("")]
   }

   #[test]
   fn gnome_wayland_ime_types_forwards_not_in_reverse() {
      let ctx = Context::default();
      let id = Id::new("secure_ime_gnome");
      let mut text = String::new();

      #[allow(deprecated)]
      run_pass(
         &ctx,
         &mut text,
         id,
         vec![Event::Ime(ImeEvent::Enabled)],
      );

      for ch in ['h', 'e', 'l', 'l', 'o'] {
         run_pass(&ctx, &mut text, id, gnome_wayland_keystroke(ch));
      }

      assert_eq!(
         text, "hello",
         "IME keystrokes must append, not insert at 0"
      );
   }

   #[test]
   fn plain_text_events_type_forwards() {
      let ctx = Context::default();
      let id = Id::new("secure_text_events");
      let mut text = String::new();

      for ch in ['h', 'e', 'l', 'l', 'o'] {
         run_pass(
            &ctx,
            &mut text,
            id,
            vec![Event::Text(ch.to_string())],
         );
      }

      assert_eq!(text, "hello");
   }

   #[test]
   fn empty_ime_preedit_without_composition_does_not_reset_cursor() {
      let ctx = Context::default();
      let id = Id::new("secure_empty_preedit");
      let mut text = String::new();

      run_pass(
         &ctx,
         &mut text,
         id,
         vec![Event::Text("ab".to_owned())],
      );
      run_pass(&ctx, &mut text, id, vec![ime_preedit("")]);
      run_pass(
         &ctx,
         &mut text,
         id,
         vec![Event::Text("c".to_owned())],
      );

      assert_eq!(
         text, "abc",
         "spurious empty Preedit must not move the cursor to the start"
      );
   }

   #[test]
   fn ime_composition_updates_replace_preedit_then_commit() {
      let ctx = Context::default();
      let id = Id::new("secure_ime_compose");
      let mut text = String::new();

      run_pass(&ctx, &mut text, id, vec![ime_preedit("n")]);
      assert_eq!(text, "n");
      run_pass(&ctx, &mut text, id, vec![ime_preedit("ni")]);
      assert_eq!(text, "ni");
      run_pass(&ctx, &mut text, id, vec![ime_preedit("に")]);
      assert_eq!(text, "に");
      run_pass(&ctx, &mut text, id, vec![ime_commit("に")]);
      assert_eq!(text, "に");
      run_pass(&ctx, &mut text, id, gnome_wayland_keystroke('!'));
      assert_eq!(text, "に!");
   }
}