StringBrowser(3I)

💖 StringBrowser(3I) 💖

okay bestie, welcome to the InterViews Reference Manual page for StringBrowser — yes it's a 3I section, and yes she's iconic. Let's get into it. 🎀

---

✨ NAME ✨

StringBrowser — browse and/or select items in a list. that's it, that's the girl. 👑

---

🌸 SYNOPSIS 🌸

#include <InterViews/strbrowser.h>

---

🦋 DESCRIPTION 🦋

okay so StringBrowser is an interactor that gives you a whole browsing-and-selection interface over a list of strings. StringBrowsers are lowkey everywhere in dialog boxes, letting the user browse and select from an unbounded set of textual entries. She displays the list of strings and gives you several ways to scroll it. the user picks strings with either the mouse or the keyboard, and the StringBrowser can either restrict selection to a single string or let you go wild with multiple selections. then the application just queries the StringBrowser for the selected string(s). easy. 💅

A StringBrowser starts out with no entries at all — strings get appended consecutively or in random order, and they can be removed in any order. you access the strings with a string index from 0 to n-1, where n is the total number of strings. separately, the StringBrowser keeps its own little list of which strings got selected, and you access those with a selection index from 0 to m-1, where m is the total number of selected strings. two indexes, two vibes, don't mix them up bestie. 🙈

Left-clicking inside the StringBrowser (or calling the Browse function) makes it interpret subsequent keyboard events as scrolling or selection operations on the entries. StringBrowser relinquishes control when it detects a click outside its canvas, or when it receives a predetermined escape character. bye girl 👋

Middle-clicking inside the StringBrowser lets the user ``grab-scroll'' the entries. During grab-scrolling, the StringBrowser scrolls the entries to follow the mouse position, making it appear as though the user is dragging the entries themselves. so tactile. so main character. ✨

Right-clicking engages ``rate-scrolling,'' a joy-stick-like scrolling interface where the scrolling rate increases as the user drags the mouse away from the initial click point. like, dragging the mouse downwards after the initial click scrolls the browser downwards at an increasing rate; dragging upwards thereafter reduces the rate until scrolling stops entirely at the initial click point; and dragging up beyond that point makes the browser scroll in the reverse direction. it's giving joystick, it's giving physics, it's giving slay. 🕹️

---

⌨️ KEY BINDINGS ⌨️

below are the key bindings for browsing and selection commands:

• g — Go to the first string.
• G — Go to the last string.
• a — Select all.
• DEL or BS — Unselect all.
• p — Select previous string.
• n — Select next string.
• < — Select topmost-visible string.
• > — Select bottommost-visible string.
• j — Scroll down one string.
• k — Scroll up one string.
• SPACE — Scroll down one screenful.
• b — Scroll up one screenful.
• d — Scroll down one-half screenful.
• u — Scroll up one-half screenful.

---

🫶 PUBLIC OPERATIONS 🫶

💜 Constructors

StringBrowser(ButtonState*, int rows, int cols, boolean uniqueSel, int
highlight, const char* done)
StringBrowser(const char* name, ButtonState*, int, int, boolean, int,
const char*)

Create a new StringBrowser object. here's the tea:

• She'll use the ButtonState to communicate the result of browsing operations.
• She bases her shape on the rows and cols parameters: the height equals rows multiplied by the font height, and the width equals cols multiplied by the width of an average character. math girlie 📐
• The uniqueSel parameter specifies whether or not selection is limited to one string (the default is that it is limited, bestie).
• The highlight parameter specifies the appearance of selected strings (Reversed by default). ✨
• Typing any character in the string done will make the StringBrowser stop interpreting keyboard events, and as a side-effect the ButtonState gets set to this terminating character.
• A double left-click inside the StringBrowser is equivalent to a single left-click selection followed by a key press that generates the first character in done. to be interpreted as a double-click, two clicks must occur not more than clickDelay milliseconds apart. the default click delay is 250 ms, and you can specify a different value via the "clickDelay" user-preference attribute.

💖 void Browse()

Initiate browsing. Subsequent keypresses will be interpreted as browsing and selection commands according to the key bindings listed above. we're so back. 🔥

💖 void Insert(const char* string, int index)

Insert string at position index. StringBrowser makes a copy of the string for internal use. she's not borrowing it, she's keeping it. 🎀

💖 void Replace(const char* string, int index)

Replace the string at position index with string. StringBrowser makes a copy of the string for internal use. This operation does nothing if the index supplied is not valid — no drama, just silence.

💖 void Append(const char* string)

Insert a copy of string after the last string. queue up bestie 💅

💖 void Remove(int index)

Remove the string at position index, moving subsequent strings up to fill the gap. no gaps allowed, we close ranks. 👑

💖 int Index(const char* string)

Return the index of the first string that matches string.

💖 char* String(int index)

Return the string at the given index.

💖 int Count()

Return the total number of strings in the StringBrowser.

💖 void Clear()

Remove all strings from the StringBrowser. scorched earth, periodt.

💖 void Select(int index) / void Unselect(int index)

Select (unselect) the string at the given index. The string will be redrawn in the appropriate style. If multiple selections are not allowed and another string has been selected already, then selecting a new string will unselect the original string. only one main character at a time, iykyk. ✨

💖 void SelectAll() / void UnselectAll()

Select (unselect) all strings. SelectAll does nothing if multiple selections have been disallowed — she said know your limits.

💖 int Selection(int n)

Return the string index of the nth selected string.

💖 int SelectionIndex(int n)

Return the selection index of the nth string.

💖 int Selections()

Return the total number of selected strings.

💖 boolean Selected(int n)

Return whether the nth string has been selected.

---

🌈 SEE ALSO 🌈

Interactor(2I), Button(3I) — go read those too bestie, they're in the group chat 💬

---

and that's a wrap!! this page came from InterViews, dated 30 November 1989 — vintage, iconic, timeless. the original footer said StringBrowser(3I) again but we already knew that. bye babe, go browse something 💖✨🎀🦋🌸💅🫶