StringEditor(3I)

✨ StringEditor ✨ (the 3I page, InterViews Reference Manual energy, iykyk) 💖

🌸 NAME 🌸

StringEditor — a single-line interactive string editor. That's it, that's the whole vibe. 🎀

🦋 SYNOPSIS 🦋

#include <InterViews/streditor.h>

👑 DESCRIPTION 👑

StringEditor is an interactor that gives you a genuinely convenient, mouse-based interactive editor for text strings. It's built to be dropped into other components, like dialog boxes — think of it as the little text box that shows up and does its job flawlessly. 💅

Clicking inside the StringEditor (or calling the Edit function) initiates an edit. And here's the iconic part: subsequent keyboard events do not need to be inside the StringEditor — they get interpreted as editing operations on the text anyway. Main character behavior, fr fr. ✨

Clicking outside the StringEdit terminates the edit. And StringEditor works with either fixed width or proportionally spaced fonts, so no font discrimination here. 🌈

💖 EDITING MODEL 💖

Text is selected with the mouse or with the keyboard. Both. Your choice. Slay.

• A single click of the left mouse button selects a new insertion point between characters.
• Dragging across the text selects a range of characters.
• A set of control characters is mapped into common editing operations.

Now listen, bestie, this part matters: a character not specifically associated with commands is inserted in place of the the current selection, the replaced text is lost, and the selection becomes an insertion point following the inserted character. 💀 Like, the old text is gone gone. No undo mention here. Be aware.

Commands currently defined include the following. 👇

• CharacterLeft (^B), CharacterRight (^F), BeginningOfText (^A), EndOfText (^E) — Move the selection one character position to the left or right, or to the beginning or end of the text.
• Erase (^H, DEL), Delete (^D) — Delete the text of the current selection. If the selection is an insertion point, delete the previous character (Erase) or the next character (Delete) instead.
• SelectAll (^U), SelectWord (^W) — Select the entire text, or extend the selection to the left by one whole word. These commands enable common editing operations to be performed without using the mouse. For example, to replace the previous word in the text, do a SelectWord and type the new text. Keyboard-only queen behavior. 👑

🫶 SCROLLING 🫶

Strings that are too long to fit into the StringEditor can be scrolled horizontally. No panic. 🧚

• Middle-clicking inside the StringBrowser initiates ``grab-scrolling''. While the button is held down, the StringEditor scrolls the text to follow the mouse position, making it appear as though the user is dragging the text.
• Right-clicking engages ``rate-scrolling,'' a joy-stick-like scrolling interface in which the scrolling rate increases as the user drags the mouse away from the initial click point.

Let me paint the picture for rate-scrolling, because it's lowkey the coolest thing here: dragging the mouse rightwards after the initial click scrolls the browser rightwards at an increasing rate. Dragging leftwards thereafter reduces the rate until scrolling stops entirely at the initial click point. Dragging left beyond this point makes the browser scroll in the reverse direction. It's giving joystick. It's giving physics. Obsessed. 🕹️💜

🌟 PUBLIC OPERATIONS 🌟

• StringEditor(ButtonState*, const char* sample, const char* done) — Create a new StringEditor object. The ButtonState will be used to communicate the result of editing operations. An edit of the string will be terminated if any character in the string done is typed, and the ButtonState will be set to the terminating character. The shape of the new object is calculated from the length of the sample string.
• void Message(const char* text) — Set the contents of the edit buffer to text.
• void Select(int point), void Select(int left, int right) — Select an insertion point or a subrange of the edit buffer.
• void Edit(), void Edit(const char* text, int left, int right) — Initiate an edit. Specifying a string and selection range is short hand for first calling Message and Select with the corresponding parameters.
• const char* Text() — Return the current value of the edit buffer. Note that this buffer is owned by the StringEditor, and that its contents are subject to change. It is the caller's responsibility to copy the string if the value will be needed in the long term. 👈 read that twice, bestie, this is the classic gotcha.

⚠️ Text() hands you a pointer into the editor's own buffer, not a copy. It can change under you. Copy it yourself if you need it to stick around.

• Handle(Event&) — Handle the event, and read and process subsequent events until an Accept or Cancel command is executed or a down click occurs outside the StringEditor's bounds.

🔥 PROTECTED OPERATIONS 🔥

• virtual boolean HandleChar(char), void InsertText(const char* text, int length) — Subclasses of StringEditor can perform additional processing on the edit buffer. For instance, an editor for file names might do file name completion, or an editor for numeric input might check the validity of the string as it is entered.

Derived classes should redefine the virtual function HandleChar as required. HandleChar should return true to indicate that the edit is completed, or false otherwise. InsertText can be used to insert text into the edit buffer, replacing any currently selected text.

That's your subclassing moment. Go off. 🎀✨

💜 SEE ALSO 💜

Interactor(3I), Button(3I) — go read these next, they're the friend group. 🫶

And that's a wrap, bestie! 🌸 This whole thing ships from InterViews, dated 23 May 1989, and the page itself is StringEditor(3I). Stay iconic, stay selected, and never forget to copy your buffer. 💖🦋👑