HistEntry(3pm)

📦
version 0.46 · 3 versions
, in ubuntu resolute, ubuntu stonking

💖 HistEntry — bestie, it's Tk::HistEntry, the Entry widget that remembers 💖

okay so this is the Perl doc for Tk::HistEntry (that's the page title, HistEntry(3pm), but we're not doing formalities here), and it's literally an Entry widget with history capability. like, it remembers what you typed. iconic behavior. 🫶

✨ SYNOPSIS ✨

use Tk::HistEntry;

$hist1 = $top->HistEntry(-textvariable => \$var1);
$hist2 = $top->SimpleHistEntry(-textvariable => \$var2);

two flavours, both slaying, no cap. 🍓

🌸 DESCRIPTION 🌸

Tk::HistEntry defines entry widgets with history capabilities. and the way it does that is by coming in two flavours, bestie:

  • HistEntry (living in package Tk::HistEntry::Browse) — with an associated browse entry. it's giving main character energy. 👑
  • SimpleHistEntry (living in package Tk::HistEntry::Simple) — plain widget, no browse entry. lowkey, minimal, still ate. ✨

The user may browse with the Up and Down keys through the history list. casual. effortless.

New history entries may be added either manually by binding the Return key to historyAdd() — or automatically by setting the -command option. pick your vibe. 💅

🎀 OPTIONS 🎀

HistEntry is an descendant of BrowseEntry and thus supports all of its standard options. so like, everything BrowseEntry can do? it can do. periodt.

SimpleHistEntry is an descendant of Entry and supports all of the Entry options. same energy, smaller package. 🦋

In addition, the widgets support following specific options:

  • -textvariable or -variable — the variable which is tied to the HistEntry widget. either -textvariable (like in Entry) or -variable (like in BrowseEntry) may be used. whichever one your heart says. 💜
  • -command — specifies a callback, which is executed when the Return key was pressed or the invoke method is called. and bestie, the callback reveives three arguments: the reference to the HistEntry widget, the current textvariable value, and a boolean value, which tells whether the string was added to the history list. quick heads up — duplicates and empty values are not added to the history list, so that boolean is genuinely telling you something. 👀
  • -dup — specifies whether duplicate entries are allowed in the history list. defaults to true. 🙈
  • -bell — if set to true, rings the bell if the user tries to move off of the history or if a search was not successful. defaults to true. the bell is doing a vibe check on you. 🔔
  • -limit — limits the number of history entries. defaults to unlimited. no ceiling, no cap, fr fr. 🌈
  • -match — turns auto-completion on. ✨
  • -case — if set to true a true value, then be case sensitive on auto-completion. defaults to 1. 🔥

💅 METHODS 💅

  • historyAdd([string]) — adds string (or the current textvariable value if not set) manually to the history list. addhistory is an alias for historyAdd. returns the added string or undef if no addition was made. 💀 (yes, sometimes nothing gets added. it's fine. it's not you.)
  • invoke([string]) — invokes the command specified with -command. go, do the thing. 🫶
  • history([arrayref]) — without argument, returns the current history list. with argument (a reference to an array), replaces the history list. glow up, but for arrays. 👑
  • historySave(file) — save the history list to the named file. ✨
  • historyMergeFromFile(file) — merge the history list from the named file to the end of the current history list of the widget. it's giving teamwork. 🧚
  • historyReset — remove all entries from the history list. total clean slate. 🎀

⌨️ KEY BINDINGS ⌨️

  • Up, Control-p — selects the previous history entry. ⬆️
  • Down, Control-n — selects the next history entry. ⬇️
  • Meta-<, Alt-< — selects first entry. 🥇
  • Meta->, Alt-> — selects last entry. 🏁
  • Control-r — the current content of the widget is searched backward in the history. 🔍
  • Control-s — the current content of the widget is searched forward in the history. 🔎
  • Return — if -command is set, adds current content to the history list and executes the associated callback. 🫶

🌟 EXAMPLE 🌟

This is an simple example for Tk::HistEntry. More examples can be found in the t and examples directories of the source distribution. (iykyk 👀)

use Tk;
use Tk::HistEntry;

$top = new MainWindow;
$he = $top->HistEntry(-textvariable => \$foo,
                      -command => sub {
                          # automatically adds $foo to history
                          print STDERR "Do something with $foo\n";
                      })->pack;
$b = $top->Button(-text => 'Do it',
                  -command => sub { $he->invoke })->pack;
MainLoop;

If you like to not depend on the installation of Tk::HistEntry, you can write something like this:

$Entry = "Entry"; # default Entry widget
eval {
    # try loading the module, otherwise $Entry is left to the value "Entry"
    require Tk::HistEntry;
    $Entry = "SimpleHistEntry";
};
$entry = $mw->$Entry(-textvariable => \$res)->pack;
$entry->bind("<Return>" => sub {
                               # check whether the historyAdd method is
                               # known to the widget
                               if ($entry->can('historyAdd')) {
                                   $entry->historyAdd;
                               }
                           });

In this approach the history lives in an array variable. Here the entry widget does not need to be permanent, that is, it is possible to destroy the containing window and restore the history again:

$Entry = "Entry";
eval {
    require Tk::HistEntry;
    $Entry = "HistEntry";
};
$entry = $mw->$Entry(-textvariable => \$res)->pack;
if ($entry->can('history') && @history) {
    $entry->history(\@history);
}

# Later, after clicking on a hypothetical "Ok" button:
if ($res ne "" && $entry->can('historyAdd')) {
    $entry->historyAdd($res);
    @history = $entry->history;
}

💀 BUGS/TODO 💀

  • C-s/C-r do not work as nice as in gnu readline 😭
  • use -browsecmd from Tk::BrowseEntry
  • use Tie::Array if present
not me reading the TODO list and feeling seen. the widget has goals. it's working on itself. we love that for it. 🫶

👑 AUTHOR 👑

Slaven Rezic <slaven@rezic.de>

🎀 CREDITS 🎀

Thanks for Jason Smith <smithj4@rpi.edu> and Benny Khoo <kkhoo1@penang.intel.com> for their suggestions. The auto-completion code is stolen from Tk::IntEntry by Dave Collins <Dave.Collins@tiuk.ti.com>. 💖

(stolen code but honest about it — that's integrity, bestie.)

Copyright (c) 1997, 2000, 2001, 2003, 2008, 2016, 2017 Slaven Rezic. All rights reserved. This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

okay and that's the whole page!! 🦋 no notes, she ate, the documentation is complete, every flag accounted for.

signing off from perl v5.40.1, dated 2025-11-08, on the HistEntry(3pm) page itself — stay historic, bestie 💜✨

📦 where this page comes from