Text Widget Options (Mastering Perl/Tk)

8.2. Text Widget Options

Options used with the Text method change the way the text is displayed within the Text widget. The following options are standard for all the widgets (see Chapter 4, " Button, Checkbutton, and Radiobutton Widgets", where the options were first covered, for further information):

-background => color: Changes the color of the screen displayed behind the text.
-borderwidth => amount: Sets the width of the edges of the widget.
-cursor => cursorname: Sets the cursor displayed when the mouse cursor is in front of the Text widget.
-exportselection => 0 | 1: Determines if the text selected within the widget can also be used by the windowing system (such as X windows).
-font => fontname: Sets the font in which the text is displayed.
-foreground => color: Sets the color of the text.
-height => amount: Sets the height of the widget. Default is 24.
-highlightbackground => color: Sets the color the highlight rectangle around the widget should be when it does not have the keyboard focus.
-highlightcolor => color: Sets the color the highlight rectangle around the widget should be when it has the keyboard focus.
-highlightthickness => amount: Sets the thickness of the highlight rectangle around the widget. Default is 2.
-insertbackground => color: Changes the color of the insert cursor.
-insertborderwidth => amount: Changes the width of the insert cursor.
-insertofftime => time: Sets the time the insert cursor blinks in the off position. Default is 300.
-insertontime => time: Sets the time the insert cursor blinks in the on position. Default is 600.
-insertwidth => amount: Sets the width of the insert cursor.
-padx => amount: Adds extra space to the left and right of the text inside the Text widget's edge.
-pady => amount: Adds extra space to the top and bottom of the text inside the Text widget's edge.
-relief => 'flat'|'groove'|'raised'|'ridge'|'sunken'|'solid': Sets the relief of the edges of the widget.
-selectbackground => color: Sets the color of the area behind the selected text.
-selectborderwidth => amount: Sets the width of the border of the selected area.
-selectforeground => color: Sets the color of the selected text.
-setgrid => 0 | 1: Enables gridding for the Text widget. Default is 0.
-spacing1 => amount: Sets the amount of additional space left on top of a line of text that begins on its own line. Default is 0.
-spacing2 => amount: Sets the amount of additional space left on top of a line of text after it has been wrapped around automatically by the Text widget. Default is 0.
-spacing3 => amount: Sets the amount of additional space left after a line of text has been ended by a "\n". Default is 0.
-state => 'normal' | 'disabled': Indicates the state of the Text widget. If set to 'disabled', no text can be inserted by either the user or the application (via the insert method).
-tabs => list: Specifies a list of tab stops to use in the Text widget. Default is every eight characters.
-takefocus => 0 | 1 | undef: Determines if widget can obtain keyboard focus.
-width => amount: Sets the width of the Text widget in characters. Default is 80.
-wrap => 'none' | 'char' | 'word': Sets the mode used to determine automatic line wrapping.
-xscrollcommand => callback: Determines the callback used when the Text widget is scrolled horizontally.
-yscrollcommand => callback: Determines the callback used when the Text widget is scrolled vertically.

8.2.1. Fonts

You can use the -font option to change the font, including how large or small the text is (see Figure 8-1). This defines the default font for the entire Text widget. Text that is inserted without a text tag (which allows you to specify formatting that applies only to certain portions of the text) will use this font.

Figure 8-1. Text widget using -font => "r16"

The use of fonts was covered in Chapter 3, "Fonts", where we first discussed the -font option.

8.2.2. Widget Size

When you first create a Text widget, it will usually have a height of 24 lines and a width of 80 characters. Depending on how you put the Text widget in its parent window (whether you use pack with the -expand and -fill options or grid with -sticky => "nsew"), it can change size when the window changes size. To force the Text widget to a certain size, you can use the -width and -height options:

# Text widget 20 characters wide and 10 lines tall
$mw->Text(-width => 20, -height => 10)->pack;

While both options take numbers, they have different units associated with them. The value associated with -width is in characters [17] and the value associated with -height is lines of text. It's possible that the Text widget will not be that exact width and height if you force the main window to be larger via the minsize routine (i.e., $mw->minsize(400,400)), especially if you used -expand => 1 and -fill => 'both' with the pack command. So if you don't see what you expect on the screen the first time out, keep this in mind.

[17]For a proportional font, the width is based on the width of the character "0".

8.2.3. Widget Style

As with other widgets, you can change how the edges of the Text widget are drawn using the -relief and -borderwidth options. The examples shown in Figure 8-2 might not look much like Text widgets, but trust me, they are (they would look much more like Text widgets if there were scrollbars associated with each widget, but we were trying to save space in the screenshot)! Figure 8-2 also shows -width and -height options to force smaller size.

Figure 8-2. Text widgets showing different -relief values

8.2.4. Line Spacing

Long lines of text can wrap around automatically if the line becomes longer than the width the Text widget can display. The amount of room left between different types of lines is defined by using the -spacingN options. Figure 8-3 shows the different areas that -spacing1, -spacing2, and -spacing3 affect.

Figure 8-3. Example of -spacingN options

The -spacing1 option affects how much room is above a new line of text (the first line in a paragraph). The -spacing2 option affects the space between lines when text that is wrapped automatically is too long to fit on one line. The -spacing3 option determines how much room is left after a paragraph is finished (right after an explicit newline).

8.2.5. Tab Stops

The default setup for Text widget tab stops is every eight characters. Each tab equals eight spaces (but it doesn't actually use spaces). You can replace this default setting by using the -tabs option as follows:

-tabs => [qw/2 center/]   # Place tabs every 2 pixels
-tabs => [2, "center"]    # The same thing, different syntax

The argument that goes with -tabs is an anonymous list that specifies positions in which to place each of the tab stops. You can also specify an optional justification value for each tab stop (as in the preceding example) after each tab stop's numerical value. This all sounds much more confusing than it really is. Here are some examples to help clarify things:

-tabs => [qw/1i center/]   # every inch, text centered on tab-stop
-tabs => [qw/1i 1.5i/]     # ts at 1 inch, 1.5 inch and every .5 inch after

The default justification is "left". The possible justification values are "left", "right", "center", and "numeric".

When you specify the values (whether in centimeters, inches, or pixels), they are not cumulative. The list ["1i", "1.5i"] translates to one tab stop 1 inch from the left edge of the Text widget and the next tab stop 1.5 inches from the left edge. If the specified list isn't long enough to span the entire window, the distance between the last two tab stops specified will be repeated across the screen.

Of course, setting up new tab stops is pretty useless unless you're doing major text editing; in most cases, you'll leave this option alone.

You can reset the tab stops back to the default by setting -tabs to undef:

$text->configure(-tabs => undef);