18.3 Common Widget Configuration Options

In the remainder of this chapter, we'll be discussing each widget: the command used to create each widget, the options used to configure them, and the methods for manipulating them.

You'll find that there are many, many configuration options that are shared by multiple widgets. We could list them individually for each widget, but in the interest of saving a tree or two, we're instead going to list the shared options up front, rather than repeating them over and over. That way we can concentrate on the options that are crucial to the behavior of each particular widget, and save the reader from being lost in a sea of options.

The following options are supported by the widgets noted:

-activebackground => color

Sets the background color when the mouse cursor is over the widget.

Applicable widgets: Button, Checkbutton, Menu, Menubutton, Optionmenu, Radiobutton, Scale, Scrollbar

-activeforeground => color

Sets the text color when the mouse cursor is over the widget. Applicable widgets: Button, Checkbutton, Menu, Menubutton, Optionmenu, Radiobutton

-anchor => position

Causes the text to stick to that position in the widget. Values for position are 'n', 'ne', 'e', 'se', 's', 'sw', 'w', 'nw', and 'center'. Applicable widgets: Button, Checkbutton, Label, Menubutton, Optionmenu, Radiobutton

-background => color

-bg => color

Sets the background of the widget to the specified color. Applicable widgets: Button, Canvas, Checkbutton, Entry, Frame, Label, Listbox, Menu, Menubutton, Optionmenu, Radiobutton, Scale, Scrollbar, Text, Toplevel

-bitmap => 'bitmapname'

Uses a bitmap instead of text in the widget. You can specify either a default bitmap or the location of a bitmap file (with @ in front of the path). Applicable widgets: Button, Checkbutton, Label, Menubutton, Optionmenu, Radiobutton

-borderwidth => amount

-bd => amount

Changes the width of the edge drawn around the widget. Applicable widgets: Button, Canvas, Checkbutton, Entry, Frame, Label, Listbox, Menu, Menubutton, Optionmenu, Radiobutton, Scale, Scrollbar, Text, Toplevel

-cursor => 'cursorname'

Mouse cursor will change to specified cursor when over the widget. Applicable widgets: Button, Canvas, Checkbutton, Entry, Frame, Label, Listbox, Menu, Menubutton, Optionmenu, Radiobutton, Scale, Scrollbar, Text, Toplevel

-disabledforeground => color

Sets the color of the text when the widget is disabled. Applicable widgets: Button, Checkbutton, Menu, Menubutton, Optionmenu, Radiobutton

-exportselection => boolean

Determines whether selected text is exported to the window system's clipboard. (For a listbox, -exportselection => 1 means two listboxes cannot have selections at the same time.) Applicable widgets: Entry, Listbox, Text

-font => 'fontname'

Changes the font of all the text on the widget to fontname. Applicable widgets: Button, Checkbutton, Entry, Label, Listbox, Menu, Menubutton, Optionmenu, Radiobutton, Scale, Text

-foreground => color

-fg => color

Changes the text color to color. Applicable widgets: Button, Checkbutton, Entry, Label, Listbox, Menu, Menubutton, Optionmenu, Radiobutton, Scale, Text

-height => amount

Specifies the height of the widget. amount represents a number of characters if text is displayed, or a screen distance if an image or bitmap is displayed. Applicable widgets: Button, Canvas, Checkbutton, Frame, Label, Listbox, Menubutton, Optionmenu, Radiobutton, Text, Toplevel

-highlightbackground => color

Sets the color of a non-focus rectangle. Applicable widgets: Button, Canvas, Checkbutton, Entry, Frame, Label, Listbox, Menubutton, Optionmenu, Radiobutton, Scale, Scrollbar, Text, Toplevel

-highlightcolor => color

Sets the color of the focus rectangle. Applicable widgets: Button, Canvas, Checkbutton, Entry, Frame, Label, Listbox, Menubutton, Optionmenu, Radiobutton, Scale, Scrollbar, Text, Toplevel

-highlightthickness => amount

Sets the thickness of the black box around the widget that indicates focus. Applicable widgets: Button, Canvas, Checkbutton, Entry, Frame, Label, Listbox, Menubutton, Optionmenu, Radiobutton, Scale, Scrollbar, Text, Toplevel

-image => $imgptr

Uses an image instead of text. $imgptr is a pointer to a Photo or Image object made using a GIF or PPM file. For example:

$image = $mainwindow->Photo(-file => "image.gif");
$mainwindow->Button(-image => $arrow,
		  -command => sub {exit})->pack;

Applicable widgets: Button, Checkbutton, Label, Menubutton, Optionmenu, Radiobutton

-insertbackground => color

Sets the color of the insert cursor. Applicable widgets: Canvas, Entry, Text

-insertborderwidth => amount

Sets the width of the insert cursor's border. Applicable widgets: Canvas, Entry, Text

-insertofftime => milliseconds

Defines the amount of time the insert cursor is "off." Applicable widgets: Canvas, Entry, Text

-insertontime => milliseconds

Defines the amount of time the insert cursor is "on." Applicable widgets: Canvas, Entry, Text

-insertwidth => amount

The width of the insert corner (default = 2 pixels). Applicable widgets: Canvas, Entry, Text

-justify => side

Justifies text against the specified side. side can be 'left', 'right', or 'center'. Applicable widgets: Button, Checkbutton, Entry, Label, Menubutton, Optionmenu, Radiobutton

-padx => amount

Adds extra space to left and right of the widget inside the widget edge. Applicable widgets: Button, Checkbutton, Label, Menubutton, Optionmenu, Radiobutton, Text

-pady => amount

Adds extra space to top and bottom of the widget inside the widget edge. Applicable widgets: Button, Checkbutton, Label, Menubutton, Optionmenu, Radiobutton, Text

-relief => type

Changes the type of edges drawn around the widget. Values for type are 'flat', 'groove', 'raised', 'ridge', and 'sunken'. Applicable widgets: Button, Canvas, Checkbutton, Entry, Frame, Label, Listbox, Menu, Menubutton, Optionmenu, Radiobutton, Scale, Scrollbar, Text, Toplevel

-selectbackground => color

Determines the background color of selected text in the entry widget. Applicable widgets: Canvas, Entry, Listbox, Text

-selectborderwidth => amount

Determines the width of the selection highlight's border. Applicable widgets: Canvas, Entry, Listbox, Text

-selectforeground => color

Determines the text color of selected text in the entry widget. Applicable widgets: Canvas, Entry, Listbox, Text

-state => state

Sets the state of responsiveness of the widget. Values for state are 'normal', 'disabled', and 'active'. (disabled makes it not respond.) Applicable widgets: Button, Checkbutton, Entry, Menubutton, Optionmenu, Scale, Text

-takefocus => focus

Determines whether the widget gets focus. Values for focus are 0 (the widget will never get the focus), 1 (the widget always gets the focus), and the null string ("") (which lets the application decide). Applicable widgets: Button, Canvas, Checkbutton, Entry, Frame, Label, Listbox, Menu, Menubutton, Optionmenu, Scale, Scrollbar, Text, Toplevel

-underline => n

Underlines the nth character in the text string. Allows keyboard input via that character when the widget has the focus. Applicable widgets: Button, Checkbutton, Label, Menubutton, Optionmenu, Radiobutton

-width => amount

Width of the widget, represented in characters if text displayed, or as a screen distance if an image or bitmap is displayed. Applicable widgets: Button, Canvas, Checkbutton, Frame, Label, Listbox, Menubutton, Optionmenu, Radiobutton, Scale, Scrollbar, Text, Toplevel

-wraplength => amount

Defines the maximum amount of text to be displayed on one line. Applicable widgets: Button, Checkbutton, Label, Menubutton, Optionmenu, Radiobutton

-xscrollcommand => callback

Assigns a callback to use when scrolling back and forth. Applicable widgets: Canvas, Entry, Listbox, Text

-yscrollcommand => callback

Determines a command to run when scrolled in the vertical direction. Applicable widgets: Canvas, Listbox, Text