5.2.2. Entry Options

The following list contains a short description of each option available for configuring an Entry widget. Several of the options are discussed in more detail later in this chapter.

5.2.3. Assigning the Entry's Contents to a Variable

-textvariable => \$variable

By now you should be familiar with this option from several of our Button examples. Any text input to the Entry widget will get assigned into $variable. The reverse also applies. Any string that gets assigned to $variable will show up in the Entry widget.

It is important to remember that no matter what the user enters, it will be assigned to this variable. This means that even if you are expecting numeric input (e.g., 314), you might get something like 3s14 if the user accidentally (or on purpose!) presses the wrong key(s). Before using any information from an Entry widget, it's a good idea to do some error checking to make sure it's the information you expect or, at the very least, in the correct format. Trying to use 3s14 in an equation would most likely produce undesired results.

$stuff = $entry->get();

You can use get whether or not you have used the -textvariable option.

5.2.4. Relief

-relief => 'flat' | 'groove' | 'raised' | 'ridge' | 'sunken'
-borderwidth => amount

Figure 5-6. Different relief types for an Entry widget: -borderwidth of 2 (the default), 4, and 10

This is the code snippet that created the five Entry widgets and used the relief name as the Entry widget's text:

foreach (qw/flat groove raised ridge sunken/) {
  $e = $mw->Entry(-relief => $_)->pack(-expand => 1);
  $e->insert('end', $_);  # put some text in the Entry
}

5.2.6. Text Selection Options

-exportselection => 0 | 1 

The -exportselection option indicates whether or not any selected text in the Entry will be put in the selection buffer in addition to being stored internal to the Entry as a selection. By leaving this option's default value, you can paste selected text into other applications.

-selectbackground => color
-selectforeground => color
-selectborderwidth => amount

Figure 5-7. Entry with -selectbackground => 'red' and -selectforeground => 'yellow'

Figure 5-8. Entry widget with -selectborderwidth => 5

5.2.7. The Insert Cursor

Figure 5-9. Default insertion cursor

You can change the thickness, border width, and width of the insertion cursor by using these options:

-insertbackground => color
-insertborderwidth => amount
-insertwidth => amount

Figure 5-10. Insertion cursor with -insertbackground => 'green' and -insertwidth => 10

Figure 5-11. -insertborderwidth => 5, -insertbackground => 'green', and -insertwidth => 10

You can change the amount of time the cursor blinks on and off by using these options:

-insertofftime => time
-insertontime => time

5.2.8. Password Entries

-show => char

Figure 5-12. Entry displaying a password

When using the -show option, the information stored in the associated $variable will contain the real information, not the asterisks.

5.2.10. Using a Scrollbar

-xscrollcommand => [ 'set' => $scrollbar ]

Figure 5-13. Scrollbar and an Entry widget

5.2.11. Configuring an Entry Widget

5.2.13. Getting the Contents of an Entry Widget

How you access the content depends on what you are going to do with the information. If you only need to reference it once in order to write it to a file or insert it into a database, it doesn't make sense to waste memory by storing it in a variable. Simply use the get method in the print statement (or wherever it would be appropriate). If the information in the Entry widget is going to be a frequently used value, such as a number for a mathematical calculation, then it makes sense to initially store it in a variable for easy access later.

5.2.14. Moving the Insertion Cursor

$entry->icursor(index);

By default, the insertion cursor starts out wherever the last insert took place. To force the insertion cursor to show up elsewhere, you could do something like this:

$e_txt = "Entry Text";
$e = $mw->Entry(-textvariable => \$e_txt)->pack( );
$e->focus;
$e->icursor(1); # put cursor at this index

5.2.15. Getting a Numeric Index Value

$numindex = $entry->index(index) ;

One of the uses of index is to find out how many characters are in the Entry widget: $length = $entry->index('end'). Of course, if we used the -textvariable option, we could get the same result by using $length = length($variable).

As an example of using index to find where the current selection starts, use this code:

$startindex = $entry->selectionPresent() ? 
                $entry->index('sel.first') : -1;

We discuss selectionPresent later in the chapter.

5.2.16. Inserting Text

The insert function will let you insert any text string at the specified index:

$entry->insert(index, string);

Here's a simple application that uses insert:

#!/usr/bin/perl
use Tk;
$mw = MainWindow->new;
$mw->title("Entry");

$e_txt = "Entry Text";    # Create Entry with initial text
$e = $mw->Entry(-textvariable => \$e_txt)->pack(-expand => 1,
                                                -fill => 'x');
$mw->Button(-text => "Exit",
            -command => sub { exit })->pack(-side => 'bottom');

# Create a Button that will insert a counter at the cursor
$i = 1;
$mw->Button(-text => "Insert #", -command => 
            sub { 
              if ($e->selectionPresent( )) {
                $e->insert('sel.last', "$i"); $i++;
              }
            })->pack;
MainLoop;

We fill the Entry widget with "Entry Text" as a default. Then we create two Buttons. The first one is the obvious Exit Button that will allow us to quit the application. The second one is a bit more complicated. When pressed, it will check to see if any text is selected in the Entry $e. If text is selected, it will insert a number that keeps track of how many times we have pressed the Insert # Button.

Figure 5-14. Using the insert method

5.2.18. Working with the Selection

$entry->selectionAdjust(index). 

You might also see the form $entry->selection('adjust', index), where 'adjust' is the first argument. Be aware that they mean the same thing as you read code written by other people.

$entry->selectionAdjust(index);

The selected text is extended toward the index (from whichever end is closest).

$entry->selectionClear( );

Any selection indicator is removed from the Entry widget, and the indexes 'sel.first' and 'sel.last' are now undefined. The selected text remains.

To reset the 'anchor' index to the specified index, use selectionFrom:

$entry->selectionFrom(index);

This does not affect any currently selected text or the indexes 'sel.first' and 'sel.last'.

The only way to check if there is a selection in the Entry widget is to use selectionPresent:

if ($entry->selectionPresent( )) {
}

It returns a 1 if there is a selection, which means you can safely use the 'sel.first' and 'sel.last' indexes (if there isn't a selection, an error will be printed when you refer to either index). selectionPresent will return a 0 if there is no current selection.

$entry->selectionRange(startindex, endindex);

The two indexes indicate where you would like the selection to cover. If startindex is the same or greater than endindex, the selection is cleared, causing 'sel.first' and 'sel.last' to be undefined. Otherwise, 'sel.first' and 'sel.last' are defined the same as startindex and endindex, respectively.

The selectionTo method causes the new selection to be set from the current 'anchor' point to the specified index:

$entry->selectionTo(index);

5.2.19. Changing the View in the Entry Widget

Figure 5-15. What $left and $right mean

When passing an index value to xview, the text in the Entry widget will shift position so that the text at the specified index is visible at the far-left edge:

$entry->xview(index);