Options (Mastering Perl/Tk)

11.3. Options

Since Frame and Toplevel widgets share similar tasks in Perl/Tk, they share similar options, as listed here. The two following sections list the options that apply to both widgets. After that we'll cover the specific options that haven't yet been covered in a previous chapter.

-background => color

11.3.1. Frame-Specific Options

Here is a list of options specific to Frame widgets:

-label => labelstring: Adds a label to the Frame with the text labelstring
-labelPack => [ pack options ]: Specifies pack options for the label
-labelVariable => \$variable: Specifies a variable that contains the text for the label

11.3.2. Toplevel-Specific Options

Here is a list of options specific to Toplevel widgets:

-menu => $menu: Indicates that the Toplevel uses the Menu in $menu across the top of the window.
-use => $windowid: $windowid is the hexadecimal window ID of the containing widget within which this Toplevel is embedded. On Win32, use the window's handle, or HWND. The -container option should also be set to true.
-screen => screenname: Sets the screen on which to place the Toplevel. Cannot be changed by the configure method.

11.3.3. Viewing a Frame

The default for a Frame widget is not to be seen. In order to see it on the screen, you need use the -relief and -borderwidth options. The default -relief is 'flat', and the default -borderwidth is 0. If you want the Frame to have any edges at all, make sure you change -borderwidth to something higher than 0. Also, unless you put something in a Frame, you'll never see it. So, for the examples in Figure 11-1, we have inserted a Label widget and an Entry widget that state the relief of that Frame. Note that this is an actual Label widget, not the -label option described in the next section.

Figure 11-1. Different relief values for Frames; -borderwidth of 2 and -borderwidth of 5

Using -relief and -borderwidth is a great way to find where your Frame is in the window. If you have a complicated window, it's confusing to remember which Frame is where. A common trick is to add -borderwidth => 5, -relief => 'groove' when creating the Frame, which makes it stand out in the window.

11.3.4. Adding a Label to a Frame

With Perl/Tk, you can add a label to your Frame by using the -label option, which takes a text string as an argument:

$mw->Frame(-label => "My Frame:")->pack;
...
# configure label in Frame later :
$frame->configure(-label => "My Frame:")->pack;

By default, the label is placed at the top of the Frame, centered across the width (see Figure 11-2). Again, we put something in the Frame so you can see the Frame as well as the item in the Frame. In this case, we placed a Button with the default pack options in the Frame. We also created the Frame with -relief => 'groove', -borderwidth => 2 so you can see the edge.

Figure 11-2. Frame with label in default position

To change the location of the label inside the Frame, use the -labelPack option. It takes an anonymous array as an argument, where the array contains any pack options for the label:

-labelPack => [ -side => 'left', -anchor => 'w']

Be careful to notice that this option has an uppercase letter in it. If you try to use -labelPack without the capital P, you'll get a compilation error. Also notice that there isn't a -labelGrid option available. You must use pack to put widgets inside your Frame if you are going to use the -label option. If you don't, your application might not run at all.

Instead of using a static text string with your Frame's label, use the -labelVariable option to assign a variable (again, notice the capital V):

-labelVariable => \$label_text

When you change the contents of the variable $label_text, the label in the Frame changes as well.

The instant you use the -label or -labelVariable option, a label is created and placed inside the Frame. You can use these options either in the initial Frame call or later with $frame->configure( ... ). If you use them later, the label is placed above all other widgets inside the Frame.

11.3.5. Frames Aren't Interactive

The Frame widget itself is not interactive. By default, it can't accept input from the user. The widgets inside it can, but the Frame cannot. As always, the focus ability is controlled by the -takefocus option:

-takefocus => 0

With a Frame widget, it is set to 0. If for some reason you need to get input from the user on your Frame, you will need to change it to -takefocus => 1.

11.3.6. Colormap Complications

When you are running several applications at once and you start a web browser, you'll sometimes notice that the colors become corrupted. When you switch from an application to the browser, the colors in your other applications suddenly change. If you switch back from your browser to an application, the browser colors change. This happens because the web browser is a color hog. It has requested more colors than the windowing system can allocate at once. The OS must alter the colormap between applications to allow the active application to use the colors it wants to use. The colormap simply gives the windowing system a way to keep track of who is using which colors.

Perl/Tk applications can have many colors too; you can get color-happy and make each Button a different color of the rainbow. This can cause problems if there are other applications running that want a lot of different colors too. If other applications are color hogs, Perl/Tk will switch to black-and-white mode. If you don't like this behavior, you can use the -colormap option to override it. -colormap takes either the word "new" or a reference to another window. If given "new", it will create its own colormap. When you use -colormap with another window, the two windows will share the colormap. But there is one catch, and that is the -visual option.

The -visual option takes as an argument a string that contains a keyword and a number. For example:

-visual => "staticgrey 2"

The keyword can be any one of the following: staticgrey, greyscale, staticcolor, pseudocolor, truecolor, or directcolor. The number indicates the depth of color used (2 = black/white).

When you use -colormap to share the colormap between two windows, the -visual option for both must be the same. This means that -visual must be undef for both (the default) or it must have the same value. Neither -colormap nor -visual can be altered by the configure method.

11.3.7. The Magical Class Option

To force your Frame or Toplevel to be in another class (besides Frame), use the -class option (see Chapter 16, "User Customization"). Simply give it a string that is a unique class identifier:

-class => 'Myframe'
-class => 'MyToplevel'