Widget...tField(3pm)

🎀 Widget...tField(3pm) — bestie edition 💅

okay so this is a page from the User Contributed Perl Documentation collection, and we're talking about Curses::Widgets::TextField. yes it's a real manual page. yes it's from 2002. yes it still slays. come sit with me 🫶

---

✨ NAME ✨

Curses::Widgets::TextField — Text Field Widgets. that's it, that's the name, she's simple and she knows it 💖

---

🌸 MODULE VERSION 🌸

$Id: TextField.pm,v 1.103 2002/11/04 00:35:44 corliss Exp corliss $

look at that version string. 1.103. iconic. no notes. ✨

---

🦋 SYNOPSIS 🦋

here's the whole vibe, bestie — copy it, paste it, live your truth:

use Curses::Widgets::TextField;

$tf = Curses::Widgets::TextField->new({
  CAPTION     => 'Name',
  CAPTIONCOL  => 'yellow',
  COLUMNS     => 10,
  MAXLENGTH   => 255,
  MASK        => undef,
  VALUE       => '',
  INPUTFUNC   => \&scankey,
  FOREGROUND  => undef,
  BACKGROUND  => 'black',
  BORDER      => 1,
  BORDERCOL   => 'red',
  FOCUSSWITCH => "\t\n",
  CURSORPOS   => 0,
  TEXTSTART   => 0,
  PASSWORD    => 0,
  X           => 1,
  Y           => 1,
  READONLY    => 0,
  });

$tf->draw($mwh, 1);

and then, because we don't gatekeep:

See the Curses::Widgets pod for other methods.

that's where the rest of the methods live. go look. i'll wait. 💜

---

💜 REQUIREMENTS 💜

• Curses
• Curses::Widgets

that's the whole list. two things. low maintenance queen. 👑

---

🌈 DESCRIPTION 🌈

so Curses::Widgets::TextField gives you simplified OO access to Curses-based single line text fields. and the way that each object maintains its own state information? obsessed. every field is its own little main character with its own memory. no sharing, no chaos, just vibes ✨

---

💅 METHODS 💅

🍓 new (inherited from Curses::Widgets)

$tf = Curses::Widgets::TextField->new({
  CAPTION     => 'Name',
  CAPTIONCOL  => 'yellow',
  COLUMNS     => 10,
  MAXLENGTH   => 255,
  MASK        => undef,
  VALUE       => '',
  INPUTFUNC   => \&scankey,
  FOREGROUND  => undef,
  BACKGROUND  => 'black',
  BORDER      => 1,
  BORDERCOL   => 'red',
  FOCUSSWITCH => "\t\n",
  CURSORPOS   => 0,
  TEXTSTART   => 0,
  PASSWORD    => 0,
  X           => 1,
  Y           => 1,
  READONLY    => 0,
  });

new instantiates a brand new TextField object, fr fr. now listen — the only mandatory key/value pairs in that config hash are X and Y. that's it. everything else? optional, babes, and here's what they all default to:

• CAPTION — default undef — caption superimposed on the border
• CAPTIONCOL — default undef — foreground colour for caption text
• COLUMNS — default 10 — number of columns displayed
• MAXLENGTH — default 255 — maximum string length allowed
• MASK — default undef — not yet implemented
• VALUE — default '' — current field text
• INPUTFUNC — default \&scankey — function to use to scan for keystrokes
• FOREGROUND — default undef — default foreground colour
• BACKGROUND — default undef — default background colour
• BORDER — default 1 — display a border around the field
• BORDERCOL — default undef — foreground colour for border
• FOCUSSWITCH — default "\t\n" — characters which signify end of input
• CURSORPOS — default 0 — starting position of the cursor
• TEXTSTART — default 0 — position in string to start displaying
• PASSWORD — default 0 — subsitutes '*' instead of characters
• READONLY — default 0 — prevents alteration to content

a few little lore drops for you, bestie:

• the CAPTION is only valid when the BORDER is enabled. if the border is disabled, the field will be underlined — provided the terminal supports it. so like, terminal-dependent, iykyk 🧚
• if MAXLENGTH is undefined, no limit will be placed on the string length. go off, type forever, no one's stopping you 💀
• if BORDER is true, the widget will be enlarged to three columns and two more columns to make room for the border. she's taking up space because she deserves it 💅

⭐ draw ⭐

$tf->draw($mwh, 1);

draw renders the text field in its current state. this requires a valid handle to a curses window in which it will render itself. and that optional second argument? if it's true, the field's text cursor gets rendered as well. cursor said "i'm here too" 🫶

---

👑 HISTORY 👑

• 1999/12/29 — original text field widget in functional model
• 2001/07/05 — first incarnation in OO architecture

she's been evolving since '99. a glow-up arc for the ages. ✨

---

💖 AUTHOR/COPYRIGHT 💖

(c) 2001 Arthur Corliss (corliss@digitalmages.com)

respect the author, bestie. 🫡

---

okay and for the cute sign-off — this was perl v5.34.0, dated 2022-06-12, and the page header/footer said Widget...tField(3pm) all along. that's the whole thing! go build a text field, you've got this 💖✨🎀🦋🌸💅🫶