NAME

Tk::PopEntry - An Entry widget with a built in right-click menu as well as predefined validation options.

SYNOPSIS

  use PopEntry;
  $dw = $parent->PopEntry(
      -pattern   => 'alpha', 'capsonly', 'signed_int', 'unsigned_int', 'float',
                 'nondigit', or any supplied regexp.
      -nomenu    => 0 or 1,
      -case      => 'upper', 'lower', 'capitalize',
      -maxwidth  => int,
      -minwidth  => int,
      -maxvalue  => int,
      -nospace   => 0 or 1,
      -menuitems => ['string', 'callback', 'binding', 'index'],
   );
   $dw->pack;

DESCRIPTION

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.

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.

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.

OPTIONS

-pattern
The pattern specified here creates an input mask for the Popentry widget. There are six pre-defined masks:

alpha - Upper and lower case a-z only.
capsonly - Upper case A-Z only.
nondigit - Any characters except 0-9.
float - A float value, which may or may not include a decimal.
signed_int - A signed integer value, which may or may not include a '+'.
unsigned_int - An unsigned integer value.

You may also specify a regular expression of your own design using Perl's standard regular expression mechanisms. Be sure to use single quotes.

-nomenu
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.

-nospace
If set to true, the user may not enter whitespace before, after or between words within that Popentry widget.

-maxwidth
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.

-maxvalue
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.

-minvalue
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.

-menuitems
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:

a string (text) that appears on the menu,
a callback (in 'package::callback' syntax format),
a binding for that option (see below),
an index value specifying where on the menu it should appear, starting at index 0.

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.

KNOWN BUGS

The -pattern option ``capsonly'' will only work properly if no more than one word is supplied.

The -minvalue only works for the first digit.

PLANNED CHANGES

Fix the issues mentioned above.

Allow individual entries to be added or removed from the menu via predefined methods.

AUTHOR

Daniel J. Berger djberg96@hotmail.com