/ 
Tk-LabPopEntry-0.05
River stage zero No dependents
/ Tk::LabPopEntry

NAME

LabPopEntry - A LabEntry widget with an automatic, configurable right-click menu built in, plus input masks.

SYNOPSIS

use LabPopEntry;
$dw = $parent->LabPopEntry(
    -pattern   => 'alpha', 'alphanum', '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 a 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.

By default, there are five items attached to the right-click menu: Cut, Copy, Paste, Delete and Sel. All. The default bindings for the items are Control-x, Control-c, Control-v, Control-d, and Control-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 => string

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

  • alpha - Upper and lower case a-z only.

  • alphanum - Alpha-numeric characters 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, e.g. '/\d\w\d/'

-nomenu => 0 or 1

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. The default is, of course, 0.

-nospace => 0 or 1

If set to true (1), the user may not enter whitespace before, after or between words within that LabPopEntry widget. The default is 0.

-maxwidth => int

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

-maxvalue => int or float

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 => int or float

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 => ['string', 'callback', '<binding>', 'underline_index']

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 nested anonymous array that contains (in this order):

  1. a string that appears on the menu,

  2. a callback (in 'package::callback' syntax format),

  3. a binding for that option (see below),

  4. an index value specifying the character in the string to be underlined.

The binding specified need only be in the form, '<Control-x>'. You needn't explicitly bind it yourself. Your callback will automatically be bound to the event sequence you specified.

METHODS

$lpe->deleteItem(index, ?index?)

Deletes the menu option at the specified index. A range of values may be deleted as well, e.g. $lpe->deleteItem(3,'end'); Returns an array reference if a single item is deleted, or a reference to an array of references if more than one item is deleted.

$lpe->addItem(?index?, $item)

Adds a menu option at the specified index, where $item is an anonymous array consisting of four elements (see the -menuitems option for details). If no index is specified, the new item will be added at the end of the menu. If an item already exists at that index, the current menu items will be "bumped" down. Returns the list of menuitems.

ADVERTISED SUBWIDGETS

$lpe->Subwidget('popupmenu')

Returns a reference to the popupmenu (a toplevel widget).

KNOWN BUGS

The -minvalue only works for the first digit.

There is still potential for odd results if your bind happens to coincide with a binding already used by the Window Manager. In windows, where I did most of my testing, this meant that Control-v would paste twice, once because MS Windows told it to, and once because I told it to.

PLANNED CHANGES

Fix the issues mentioned above.

Automatically bind the 'Alt' key to the underlined character.

Give the option to remove bindings completely.

AUTHOR

Daniel J. Berger djberg96@hotmail.com

SEE ALSO

Entry, LabEntry