<HTML>
<HEAD>
<TITLE>LabPopEntry.pm</TITLE>
<LINK REV="made" HREF="mailto:">
</HEAD>
<BODY>
<A NAME="__index__"></A>
<!-- INDEX BEGIN -->
<UL>
<LI><A HREF="#name">NAME</A></LI>
<LI><A HREF="#synopsis">SYNOPSIS</A></LI>
<LI><A HREF="#options">OPTIONS</A></LI>
<LI><A HREF="#planned changes">PLANNED CHANGES</A></LI>
<LI><A HREF="#author">AUTHOR</A></LI>
<LI><A HREF="#see also">SEE ALSO</A></LI>
</UL>
<!-- INDEX END -->
<HR>
<P>
<H1>NAME</H1>
Tk::LabPopEntry - A LabEntry widget with a built in right-click menu as well as
predefined validation options.
<BR>
<HR>
<P>
<H1><A NAME="synopsis">SYNOPSIS</A></H1>
<PRE>
use LabPopEntry;
$dw = $parent->LabPopEntry(
-pattern => 'alpha', 'capsonly', 'signed_int', 'unsigned_int', 'float',
'nondigit', or any supplied regexp.
-nomenu => 0 or 1,
-case => 'upper', 'lower', 'capitalize',
-maxwidth => int,
-minvalue => int,
-maxvalue => int,
-nospace => 0 or 1,
-menuitems => ['string', 'callback', 'binding', 'index'],
);
$dw->pack;
</PRE>
<P>
<HR>
<P>
<H1>DESCRIPTION</H1>
<P>LabPopEntry is an LabEntry widget with a right-click menu automatically attached.
In addition, certain field masks can easily be applied to the entry widget in
order to force the end-user into entering only the values you want him or her
to enter.</P>
<P>
Note that a LabPopEntry is derived from a LabEntry widget, and hence has the
'label' and 'labelPack' options available to it. It is otherwise virtually
identical to a PopEntry widget.
</P>
<P>By default, there are five items attached to the right-click menu: Cut, Copy,
Paste, Delete and Select All. The default bindings for the items are ctrl-x,
ctrl-c, ctrl-v, ctrl-d, and ctrl-a, respectively.</P>
<P>The difference between 'Cut' and 'Delete' is that the former automatically
copies the contents that were cut to the clipboard, while the latter does not.</P>
<P>
<P>
<HR>
<H1><A NAME="options">OPTIONS</A></H1>
<P><B>-pattern</B>
<BR>
The pattern specified here creates an input mask for the LabPopEntry widget.
There are six pre-defined masks:
<BR><BR>
alpha - Upper and lower case a-z only.
<BR>
capsonly - Upper case A-Z only.
<BR>
nondigit - Any characters except 0-9.
<BR>
float - A float value, which may or may not include a decimal.
<BR>
signed_int - A signed integer value, which may or may not include a '+'.
<BR>
unsigned_int - An unsigned integer value.</P>
<P>You may also specify a regular expression of your own design using Perl's
standard regular expression mechanisms. Be sure to use single quotes.</P>
<P>
<P><B>-nomenu</B>
<BR>
If set to true, then no right-click menu will appear. Presumably, you would
set this if you were only interested in the input-mask functionality.</P>
<P><B>-nospace</B>
<BR>
If set to true, the user may not enter whitespace before, after or between
words within that LabPopEntry widget.</P>
<P><B>-maxwidth</B>
<BR>
Specifies the maximum number of characters that the user can enter in that
particular LabPopEntry widget. Note that this is not the same as the width
of the widget.</P>
<P><B>-maxvalue</B>
<BR>
If one of the pre-defined numeric patterns is chosen, this specifies the
maximum allowable value that may be entered by a user for the widget.</P>
<P><B>-minvalue</B>
<BR>
If one of the pre-defined numeric patterns is chosen, this specifies the
minimum allowable value for the first digit (0-9). This should work better.</P>
<P><B>-menuitems</B>
<BR>
If specified, this creates a user-defined right-click menu rather than
the one that is provided by default. The value specified must be a four
element anonymous array that contains:</P>
<P>
<UL>
<LI>a string (text) that appears on the menu,
<LI>a callback (in 'package::callback' syntax format),
<LI>a binding for that option (see below),
<LI>an index value specifying where on the menu it should appear, starting at
index 0.
</UL></P>
<P>
The binding specified need only be in the form, '<ctrl-x>'. You needn't
explicitly bind it yourself. Your callback will automatically be bound to
the event sequence you specified.
<P>
<HR>
<H1>NOTES</H1>
<P>
This widget is functionally identical to the PopEntry widget, with the exception
that a label may be added since it is derived from a LabEntry widget rather than
an Entry widget.
</P>
<P>
In terms of code, this widget was completely re-written. I am now using a
'Key' binding to check for validation, rather than overloading the 'insert'
method of the Entry widget. Also, the toplevel menu is now available as an
advertised subwidget, making for much easier configuration of the right-click
menu.
</P>
<P>
Be careful with any manual regular expressions supplied to the 'pattern' option.
Remember that the validation occurs character by character, so something like
'\d\d' (any two numbers) will fail, since the validation will check the moment
the user enters the first number, only to find that there aren't two numbers.
</P>
<HR>
<H1>KNOWN BUGS</H1>
<P>The -pattern option ``capsonly'' will only work properly if no more than one
word is supplied.</P>
<P>The -minvalue only works for the first digit.</P>
<P>The -float option will allow two '.', if one of them is at the beginning of
a number.
<P>
<P>
<HR>
<H1><A NAME="planned changes">PLANNED CHANGES</A></H1>
<P>Fix the issues mentioned above.</P>
<P>Allow individual entries to be added or removed from the menu via predefined
methods.</P>
<P>
<HR>
<H1><A NAME="author">AUTHOR</A></H1>
<P>Daniel J. Berger
<A HREF="mailto:djberg96@hotmail.com">djberg96@hotmail.com</A></P>
<P>
<HR>
<H1><A NAME="see also">SEE ALSO</A></H1>
<P>Entry</P>
</BODY>
</HTML>