LabPopEntry.pm

- NAME
- SYNOPSIS
- OPTIONS
- PLANNED CHANGES
- AUTHOR
- SEE ALSO

# NAME

Tk::LabPopEntry - A LabEntry widget with a built in right-click menu as well as predefined validation options.

# SYNOPSIS

      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;

# DESCRIPTION

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.

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.

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 LabPopEntry 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 LabPopEntry widget.

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

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

# NOTES

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.

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.

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.

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

The -float option will allow two '.', if one of them is at the beginning of a number.

# 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

# SEE ALSO

Entry