User Customization

Contents:

Using the Command Line
Using the Option Database

When writing Perl/Tk applications, we can change the look of the application dramatically by using different options when creating widgets. We can give our users a similar type of control using the resource database or command-line options. The user has the ability to change the appearance of almost anything, from the width of widget edges and the fonts used to display text to the cursor shown as the mouse passes over a widget. A change can be global to every application that honors the option database or so specific that it changes a single option of a single widget.

In the first part of this chapter, we'll cover the ways users can change these visual aspects from the command line. Later in the chapter, we'll give you more ideas on how to utilize a resource database.

The term resource database originated in the X Window System. Essentially, the resource database provides user-specified values for widget configuration options. When creating a new widget, Tk queries the resource database for all options that the developer did not explicitly specify on the widget creation command. If an option/value pair (sometimes called a resource) isn't found in the resource database, Tk uses the option's default value provided by the widget's class.

Actually, a resource is a bit more complicated. Although the resource identifies a single option/value pair, it may apply to more than a single widget. Using class names and the wildcard character (*), it's possible to pattern match multiple widgets. Each of those widgets subsequently has that particular option configured.

So, an option database resource is really a pattern/value pair. Resources have this general syntax:

pattern : value

where pattern identifies an option for one or more widgets and value is the value to assign to all matches. The colon acts as a separator (with or without whitespace). We'll see what all this means later.

Tk doesn't use the classical Unix resource database, but its own implementation, called the option database. Except for minor details, using the option database is identical to the resource database; thus, we'll use the two terms interchangeably.

Perl/Tk handles the option database slightly differently than Tcl/Tk. Prior to MainWindow creation, Perl/Tk calls the special command-line processing subroutine Tk::CmdLine::SetArguments. This subroutine extracts standard X11 options such as -background and adds them to the option database. Options that Tk::CmdLine::SetArguments doesn't recognize are left in @ARGV for the application to handle. We'll learn more about the Tk::CmdLine subroutines later.

When determining the value to assign to an option, Perl/Tk uses this order of precedence:

• If the developer specified an option on a widget creation command, that value is used. It cannot be overridden by the option database.
• For an unspecified option, the option database is consulted. If a resource entry matches, the option database value is used for the widget option. As mentioned previously, this value may have come from the command line.
• Otherwise, Perl/Tk uses the default value supplied by the widget's class.
• All other command-line options remain in @ARGV.

Using the Command Line

You need to leave a way open for customization in your application. Mainly, this means you can take the easy way out and not hardcode many option values. If you hardcode too many configuration options, users cannot easily tailor your application using one of the methods listed in this chapter. For example, if you want to allow your users to change the font of all the widgets in the application, don't use the -font option when creating or configuring your widgets. If you want to do something such as change the size of a font, get the current font and then change the size.[40]

[40] Sometimes your code might depend on the size of the font used (see NavListbox in "Creating Custom Widgets in Pure Perl/Tk"). Rather than limiting your users or having your window look wrong, just determine the current font and calculate from there.

Often the easiest thing for a user to do is specify a command-line option when running the application. The options can be changed quickly and allow users to have immediate and direct control over their applications.

There are several command-line options that customize the way your application looks. When you run your application, the command line looks something like this:[41]

[41] In real life, MS Windows users might double-click on the pl file or use a shortcut, but let's assume for now that you're typing this at a DOS prompt.

# On MS Windows systems: > perl myScript.pl [ options... ] # On Unix systems: % myScript [ options... ]

The supported options are standard X options that any user familiar with X Windows will recognize. None of these options are required, but they might be the simplest ways to do what you want (for example, changing the background color of everything in the application). When specifying a command-line list of options and values, do not use a comma separator. If any of the options have bad values, you'll get an immediate error, and the application won't run.

Customizing using only command-line options won't necessarily produce the most elegant-looking applications, but for something simple, such as changing colors or fonts, it's the quickest way to go. Also, remember that an option can't be changed by the user if you have set it inside the application. Table 16-1 lists the options that Tk::CmdLine::SetArguments recognizes.

Table 16-1. Command-line options recognized by Tk::CmdLine::SetArguments

Colors, Fonts, and Titles

Changing all colors in an application is simplified by using the -background and -foreground command-line options. Each takes a color argument; it is wise to use contrasting colors since whatever you use for -foreground will be the text color.

Here's an example that changes your application to white on black:

% myScript.pl -foreground white -background black

If you are fond of a particular color for the text, use just the -foreground option:

% myScript.pl -foreground purple

To change the font of all widgets in the application, use the -font command-line option:

% myScript.pl -font "Arial 14"

For more information on fonts, take a look at "Fonts".

Normally the title of a running Perl/Tk application is either its filename (excluding any extension), the value associated with the -title option when creating/configuring the MainWindow, or the title established with the title method. If the title isn't explicitly set, a user can use the -title command-line option:

% myScript.pl -title "This is my app!"

Initial MainWindow Placement

When you run a Perl/Tk application, the MainWindow immediately appears on the screen. If you would rather the window manager not display the MainWindow, specify the -iconic option on the command line:

% myScript.pl -iconic

In Windows, you'll see an entry on the Taskbar. For a Unix system, the icon is placed however your window manager normally does these things (perhaps in an icon bay, as an icon on the desktop, or not shown at all). This is a great way to start an application that has a lot of tasks to do (similar to a batch job), but you still want to be able to see the output in a nice format later. The program can even be written to deiconify itself if something urgent happens while it's running.

With the -geometry option, you can change the initial size and/or position of your application. To change the size of the MainWindow, use the -geometry option:

% myScript.pl -geometry "100x300"

The complete syntax for -geometry is:

widthxheight{+-}xoffset{+-}yoffset

where width and height are the window's x and y dimensions. If an offset value is positive, it is measured from the top or left edge of the display, and if negative, it is measured from the bottom or right edge of the screen. For example, a specification of -0-0 would place an application in the bottom-right corner of the display.

Choosing a Display

On Unix systems, you'll have to specify the full display name (take a look at the DISPLAY environment variable or look on the X manpage under Display Names for a bit more information). See "IPC with send" for complete details on DISPLAY and friends. It's normally set up automatically, although you can change it using the -display or -screen options.

Option Database Lookups

When using the option database, a resource pattern often contains class and application names. You can change these values for your application via the command-line options -class and -name. Using these options makes sense if you want to run the application several times simultaneously and easily distinguish between the different applications at a glance. You can make the one that points to a development server all blue and the production one red or green.

Further, you can pre-populate the option database by using the -xrm option with a value. The value is a standard pattern:value string. You can specify multiple -xrm pattern/value pairs as well, making this a very powerful command-line option. This option is particularly useful for adding options that do not have command-line equivalents.

% perl myScript.pl -xrm '*font: Arial 14' -xrm '*foreground: blue' -xrm '*pi: 3.14'

Synchronizing Window Messages

Normally your Perl/Tk application runs asynchronously, which means X messages are buffered. To turn off this buffering, use the -synchronous option. This is mainly a debugging technique, but we Perl/Tk developers should never have to resort to it.