option(3)

NAME

option - Using the option database in Perl/Tk

SYNOPSIS

$widget->widgetClass(Name=>name, -class=>class);
$widget->PathName;
$widget->optionAdd(pattern=>value  ?,priority?);
$widget->optionClear;
$widget->optionGet(name, class);
$widget->optionReadfile(fileName ?,priority?);

DESCRIPTION

The option database (also known as the resource database or the application defaults database) is a set of rules for applying default options to widgets. Users and system
administrators can set up these rules to customize the
appearance of applications without changing any applica
tion code; for example, a user might set up personal fore
ground and background colors, or a site might use fonts
associated with visual or language preferences. Different
window managers (and implementations of them) have imple
mented the database differently, but most Xt-based window
managers use the .Xdefaults file or the xrdb utility to manage user preferences; some use both, and/or implement a
more complex set of site, user and application databases.
Check your site documentation for these topics or your
window manager's RESOURCE_MANAGER property.

Being a good citizen

For most applications, the option database "just works."
The option... methods are for applications that need to do something unusual, such as add new rules or test an
option's default. Even in such cases, the application
should provide for user preferences. Do not hardcode wid
get options without a very good reason. All users have
their own tastes and they are all different. They choose
a special font in a special size and have often spend a
lot of time working out a color scheme that they will love
until death. When you respect their choices they will
enjoy working with your applications much more. Don't
destroy the common look and feel of a personal desktop.

Option rules and widget identification

All widgets in an application are identified hierarchi
cally by pathname, starting from the MainWindow and pass ing through each widget used to create the endpoint. The
path elements are widget names, much like the elements of a file path from the root directory to a file. The rules
in the option database are patterns that are matched
against a widget's pathname to determine which defaults apply. When a widget is created, the Name option can be
used to assign the widget's name and thus create a dis
tinctive path for widgets in an application. If the Name
option isn't given, Perl/Tk assigns a default name based
on the type of widget; a MainWindow's default name is the appname. These defaults are fine for most widgets, so
don't feel you need to find a meaningful name for every
widget you create. A widget must have a distinctive name
to allow users to tailor its options independently of
other widgets in an application. For instance, to create
a Text widget that will have special options assigned to
it, give it a name such as:: $text = $mw->Text(Name => 'importantText');
You can then tailor the widget's attributes with a rule in the option database such as:: *importantText*foreground: red
The class attribute identifies groups of widgets, usually
within an application but also to group similar widgets
among different applications. One typically assigns a
class to a TopLevel or Frame so that the class will apply to all of that widget's children. To extend the example,
we could be more specific about the importantText widget
by giving its frame a class:: $frame = $mw->Frame(-class => 'Urgent');
$text = $frame->Text(Name => 'importantText');
Then the resource pattern can be specified as so:: *Urgent*importantText*foreground: red
Similarly, the pattern "*Urgent*background: cyan" would apply to all widgets in the frame.

METHODS

$widget->widgetClass(Name=>name, -class=>class);: Identify a new widget with name and/or class. Name specifies the path element for the widget; names gen
erally begin with a lowercase letter. -class speci
fies the class for the widget and its children;
classes generally begin with an uppercase letter. If
not specified, Perl/Tk will assign a unique default
name to each widget. Only MainWindow widgets have a default class, made by uppercasing the first letter of
the application name.
$widget->PathName;: The PathName method returns the widget's pathname, which uniquely identifies the widget within the appli
cation.
$widget->optionAdd(pattern=>value ?, priority?);: The optionAdd method adds a new option to the
database. Pattern contains the option being speci
fied, and consists of names and/or classes separated
by asterisks or dots, in the usual X format. Value
contains a text string to associate with pattern; this is the value that will be returned in calls to the
optionGet method. If priority is specified, it indi cates the priority level for this option (see below
for legal values); it defaults to interactive. This method always returns an empty string.
$widget->optionClear;: The optionClear method clears the option database. Default options (from the RESOURCE_MANAGER property or the .Xdefaults file) will be reloaded automatically the next time an option is added to the database or
removed from it. This method always returns an empty
string.
$widget->optionGet(name,class);: The optionGet method returns the value of the option specified for $widget under name and class. To look up the option, optionGet matches the patterns in the resource database against $widget's pathname along with the class of $widget (or its parent if $widget has no class specified). The widget's class and name
are options set when the widget is created (not
related to class in the sense of bless); the MainWin dow's name is the appname and its class is (by default) derived from the name of the script.; If several entries in the option database match $wid_
get's pathname, name, and class, then the method returns whichever was created with highest priority level. If there are several matching entries at the
same priority level, then it returns whichever entry
was most recently entered into the option database. If there are no matching entries, then the empty
string is returned.
$widget->optionReadfile(fileName?,priority?);: The optionReadfile method reads fileName, which should have the standard format for an X resource database
such as .Xdefaults, and adds all the options specified in that file to the option database. If priority is specified, it indicates the priority level at which to
enter the options; priority defaults to interactive.; The priority arguments to the option methods are nor mally specified symbolically using one of the follow
ing values:; widgetDefault
Level 20. Used for default values hard-coded
into widgets.
startupFile: Level 40. Used for options specified in
application-specific startup files.
userDefault: Level 60. Used for options specified in userspecific defaults files, such as .Xdefaults, resource databases loaded into the X server,
or user-specific startup files.
interactive: Level 80. Used for options specified interac
tively after the application starts running.
If priority isn't specified, it defaults to this level.
Any of the above keywords may be abbreviated. In addition, priorities may be specified numerically using integers between 0 and 100, inclusive. The numeric form is probably a bad idea except for new priority levels other than the ones given above.

BUGS

The priority scheme used by core Tk is not the same as
used by normal Xlib routines. In particular is assumes
that the order of the entries is defined, but user com
mands like xrdb -merge can change the order.

KEYWORDS

database, option, priority, retrieve

docs.sk

comprehensive documentation repository

In section