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 application
code; for example, a user might set up personal foreground and background
colors, or a site might use fonts associated with visual or language
preferences. Different window managers (and implementations of them) have
implemented 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
widget 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.
All widgets in an application are identified hierarchically by
pathname,
starting from the
MainWindow and passing 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 distinctive 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 generally
begin with a lowercase letter. -class specifies 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
application.
- $widget->optionAdd(pattern=>value
?, priority?);
- The optionAdd method adds a new option to the
database. Pattern contains the option being specified, 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 indicates 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 MainWindow'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
$widget'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 normally
specified symbolically using one of the following 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 user-specific
defaults files, such as .Xdefaults, resource databases loaded into
the X server, or user-specific startup files.
- interactive
- Level 80. Used for options specified interactively 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 commands like
xrdb -merge can change the order.
SEE ALSO¶
Tk::Xrm
KEYWORDS¶
database, option, priority, retrieve