[Chapter 18] 18.3 Common Widget Configuration Options
Author: Ellen Siever, Stephen Spainhour & Nathan Patwardhan
Date: 1999-07-02T01:58:49Z

#

| Chapter 18 Perl/Tk |

## 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 `n`th 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

18.2 Geometry Managers |  | 18.4 The Button Widget