.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "HistEntry 3pm"
.TH HistEntry 3pm "2022-06-28" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Tk::HistEntry \- Entry widget with history capability
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Tk::HistEntry;
\&
\&    $hist1 = $top\->HistEntry(\-textvariable => \e$var1);
\&    $hist2 = $top\->SimpleHistEntry(\-textvariable => \e$var2);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Tk::HistEntry\*(C'\fR defines entry widgets with history capabilities. The widgets
come in two flavours:
.ie n .IP """HistEntry"" (in package ""Tk::HistEntry::Browse"") \- with associated browse entry" 4
.el .IP "\f(CWHistEntry\fR (in package \f(CWTk::HistEntry::Browse\fR) \- with associated browse entry" 4
.IX Item "HistEntry (in package Tk::HistEntry::Browse) - with associated browse entry"
.PD 0
.ie n .IP """SimpleHistEntry"" (in package ""Tk::HistEntry::Simple"") \- plain widget without browse entry" 4
.el .IP "\f(CWSimpleHistEntry\fR (in package \f(CWTk::HistEntry::Simple\fR) \- plain widget without browse entry" 4
.IX Item "SimpleHistEntry (in package Tk::HistEntry::Simple) - plain widget without browse entry"
.PD
.PP
The user may browse with the \fBUp\fR and \fBDown\fR keys through the history list.
New history entries may be added either manually by binding the
\&\fBReturn\fR key to \fB\fBhistoryAdd()\fB\fR or
automatically by setting the \fB\-command\fR option.
.SH "OPTIONS"
.IX Header "OPTIONS"
\&\fBHistEntry\fR is an descendant of \fBBrowseEntry\fR and thus supports all of its
standard options.
.PP
\&\fBSimpleHistEntry\fR is an descendant of \fBEntry\fR and supports all of the
\&\fBEntry\fR options.
.PP
In addition, the widgets support following specific options:
.IP "\fB\-textvariable\fR or \fB\-variable\fR" 4
.IX Item "-textvariable or -variable"
Variable which is tied to the HistEntry widget. Either \fB\-textvariable\fR (like
in Entry) or \fB\-variable\fR (like in BrowseEntry) may be used.
.IP "\fB\-command\fR" 4
.IX Item "-command"
Specifies a callback, which is executed when the Return key was pressed or
the \fBinvoke\fR method is called. 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 (e.g. duplicates and empty values are not added to the history list).
.IP "\fB\-dup\fR" 4
.IX Item "-dup"
Specifies whether duplicate entries are allowed in the history list. Defaults
to true.
.IP "\fB\-bell\fR" 4
.IX Item "-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.
.IP "\fB\-limit\fR" 4
.IX Item "-limit"
Limits the number of history entries. Defaults to unlimited.
.IP "\fB\-match\fR" 4
.IX Item "-match"
Turns auto-completion on.
.IP "\fB\-case\fR" 4
.IX Item "-case"
If set to true a true value, then be case sensitive on
auto-completion. Defaults to 1.
.SH "METHODS"
.IX Header "METHODS"
.IP "\fBhistoryAdd(\fR[\fIstring\fR]\fB)\fR" 4
.IX Item "historyAdd([string])"
Adds string (or the current textvariable value if not set) manually to the
history list. \fBaddhistory\fR is an alias for \fBhistoryAdd\fR. Returns the
added string or undef if no addition was made.
.IP "\fBinvoke(\fR[\fIstring\fR]\fB)\fR" 4
.IX Item "invoke([string])"
Invokes the command specified with \fB\-command\fR.
.IP "\fBhistory(\fR[\fIarrayref\fR]\fB)\fR" 4
.IX Item "history([arrayref])"
Without argument, returns the current history list. With argument (a
reference to an array), replaces the history list.
.IP "\fBhistorySave(\fR\fIfile\fR\fB)\fR" 4
.IX Item "historySave(file)"
Save the history list to the named file.
.IP "\fBhistoryMergeFromFile(\fR\fIfile\fR\fB)\fR" 4
.IX Item "historyMergeFromFile(file)"
Merge the history list from the named file to the end of the current
history list of the widget.
.IP "\fBhistoryReset\fR" 4
.IX Item "historyReset"
Remove all entries from the history list.
.SH "KEY BINDINGS"
.IX Header "KEY BINDINGS"
.IP "\fBUp\fR, \fBControl-p\fR" 4
.IX Item "Up, Control-p"
Selects the previous history entry.
.IP "\fBDown\fR, \fBControl-n\fR" 4
.IX Item "Down, Control-n"
Selects the next history entry.
.IP "\fBMeta\-<\fR, \fBAlt\-<\fR" 4
.IX Item "Meta-<, Alt-<"
Selects first entry.
.IP "\fBMeta\->\fR, \fBAlt\->\fR" 4
.IX Item "Meta->, Alt->"
Selects last entry.
.IP "\fBControl-r\fR" 4
.IX Item "Control-r"
The current content of the widget is searched backward in the history.
.IP "\fBControl-s\fR" 4
.IX Item "Control-s"
The current content of the widget is searched forward in the history.
.IP "\fBReturn\fR" 4
.IX Item "Return"
If \fB\-command\fR is set, adds current content to the history list and
executes the associated callback.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
This is an simple example for Tk::HistEntry. More examples can be
found in the t and examples directories of the source distribution.
.PP
.Vb 2
\&    use Tk;
\&    use Tk::HistEntry;
\&
\&    $top = new MainWindow;
\&    $he = $top\->HistEntry(\-textvariable => \e$foo,
\&                          \-command => sub {
\&                              # automatically adds $foo to history
\&                              print STDERR "Do something with $foo\en";
\&                          })\->pack;
\&    $b = $top\->Button(\-text => \*(AqDo it\*(Aq,
\&                      \-command => sub { $he\->invoke })\->pack;
\&    MainLoop;
.Ve
.PP
If you like to not depend on the installation of Tk::HistEntry, you
can write something like this:
.PP
.Vb 10
\&    $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 => \e$res)\->pack;
\&    $entry\->bind("<Return>" => sub {
\&                                   # check whether the historyAdd method is
\&                                   # known to the widget
\&                                   if ($entry\->can(\*(AqhistoryAdd\*(Aq)) {
\&                                       $entry\->historyAdd;
\&                                   }
\&                               });
.Ve
.PP
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:
.PP
.Vb 9
\&    $Entry = "Entry";
\&    eval {
\&        require Tk::HistEntry;
\&        $Entry = "HistEntry";
\&    };
\&    $entry = $mw\->$Entry(\-textvariable => \e$res)\->pack;
\&    if ($entry\->can(\*(Aqhistory\*(Aq) && @history) {
\&        $entry\->history(\e@history);
\&    }
\&
\&    # Later, after clicking on a hypothetical "Ok" button:
\&    if ($res ne "" && $entry\->can(\*(AqhistoryAdd\*(Aq)) {
\&        $entry\->historyAdd($res);
\&        @history = $entry\->history;
\&    }
.Ve
.SH "BUGS/TODO"
.IX Header "BUGS/TODO"
.Vb 3
\& \- C\-s/C\-r do not work as nice as in gnu readline
\& \- use \-browsecmd from Tk::BrowseEntry
\& \- use Tie::Array if present
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Slaven Rezic <slaven@rezic.de>
.SH "CREDITS"
.IX Header "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>.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
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.