<HTML>
<HEAD>
<TITLE>PopEntry.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::PopEntry - An Entry 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 PopEntry;
 $dw = $parent-&gt;PopEntry(
     -pattern   =&gt; 'alpha', 'capsonly', 'signed_int', 'unsigned_int', 'float',
                'nondigit', or any supplied regexp.
     -nomenu    =&gt; 0 or 1,
     -case      =&gt; 'upper', 'lower', 'capitalize',
     -maxwidth  =&gt; int,
     -minwidth  =&gt; int,
     -maxvalue  =&gt; int,
     -nospace   =&gt; 0 or 1,
     -menuitems =&gt; ['string', 'callback', 'binding', 'index'],
  );
  $dw-&gt;pack;
</PRE>
<P>
<HR>
<P>
<H1>DESCRIPTION</H1>
<P>PopEntry is an Entry 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>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>&nbsp;&nbsp;&nbsp;&nbsp;
  The pattern specified here creates an input mask for the Popentry 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>&nbsp;&nbsp;&nbsp;&nbsp;
  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>&nbsp;&nbsp;&nbsp;&nbsp;
  If set to true, the user may not enter whitespace before, after or between
words within that Popentry widget.</P>
<P><B>-maxwidth</B>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;
  Specifies the maximum number of characters that the user can enter in that
particular Popentry widget.  Note that this is not the same as the width
of the widget.</P>
<P><B>-maxvalue</B>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;
  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>&nbsp;&nbsp;&nbsp;&nbsp;
  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>&nbsp;&nbsp;&nbsp;&nbsp;
  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, '&lt;ctrl-x&gt;'.  You needn't
explicitly bind it yourself.  Your callback will automatically be bound to
the event sequence you specified.
<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>
<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:[email protected]">[email protected]</A></P>
<P>
<HR>
<H1><A NAME="see also">SEE ALSO</A></H1>
<P>Entry</P>

</BODY>

</HTML>