.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "option 3pm"
.TH option 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Tk::option \- Using the option database in Perl/Tk
.SH SYNOPSIS
.IX Header "SYNOPSIS"
\ \ \ \ \fR\f(CI$widget\fR\fI\fR\->\fBwidgetClass\fR(\fBName\fR=>\fIname\fR, \fB\-class\fR=>\fIclass\fR);
.PP
\ \ \ \ \fR\f(CI$widget\fR\fI\fR\->\fBPathName\fR;
.PP
\ \ \ \ \fR\f(CI$widget\fR\fI\fR\->\fBoptionAdd\fR(\fIpattern\fR=>\fIvalue \fR ?,\fIpriority\fR?);
.PP
\ \ \ \ \fR\f(CI$widget\fR\fI\fR\->\fBoptionClear\fR;
.PP
\ \ \ \ \fR\f(CI$widget\fR\fI\fR\->\fBoptionGet\fR(\fIname, class\fR);
.PP
\ \ \ \ \fR\f(CI$widget\fR\fI\fR\->\fBoptionReadfile\fR(\fIfileName\fR ?,\fIpriority\fR?);
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The option database (also known as the \fIresource database\fR or the
\&\fIapplication defaults database\fR) 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
\&\fI.Xdefaults\fR file or the \fIxrdb\fR 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 \fBRESOURCE_MANAGER\fR property.
.SS "Being a good citizen"
.IX Subsection "Being a good citizen"
For most applications, the option database "just works."  The \fBoption...\fR
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 \fBvery\fR 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.
.SS "Option rules and widget identification"
.IX Subsection "Option rules and widget identification"
All widgets in an application are identified hierarchically by \fIpathname\fR,
starting from the \fBMainWindow\fR and passing through each widget used to create
the endpoint.  The path elements are \fIwidget names\fR, 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 \fIpathname\fR to
determine which defaults apply.
When a widget is created, the \fBName\fR option can be
used to assign the widget's name and thus create a distinctive path
for widgets in an application.  If the \fBName\fR option isn't given,
Perl/Tk assigns a default name based on the type of widget; a
\&\fBMainWindow\fR's default name is the \fBappname\fR.  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 \fBText\fR widget that will
have special options assigned to it, give it a name such as:
.PP
.Vb 1
\&  $text = $mw\->Text(Name => \*(AqimportantText\*(Aq);
.Ve
.PP
You can then tailor the widget's attributes with a rule in the option
database such as:
.PP
.Vb 1
\&  *importantText*foreground: red
.Ve
.PP
The \fIclass\fR 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 \fBTopLevel\fR or \fBFrame\fR 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:
.PP
.Vb 2
\&  $frame = $mw\->Frame(\-class => \*(AqUrgent\*(Aq);
\&  $text = $frame\->Text(Name => \*(AqimportantText\*(Aq);
.Ve
.PP
Then the resource pattern can be specified as so:
.PP
.Vb 1
\&  *Urgent*importantText*foreground: red
.Ve
.PP
Similarly, the pattern \f(CW\*(C`*Urgent*background: cyan\*(C'\fR would apply to all
widgets in the frame.
.SH METHODS
.IX Header "METHODS"
.ie n .IP "\fR\fI$widget\fR\fI\fR\->\fBwidgetClass\fR(\fBName\fR=>\fIname\fR, \fB\-class\fR=>\fIclass\fR);" 4
.el .IP "\fR\f(CI$widget\fR\fI\fR\->\fBwidgetClass\fR(\fBName\fR=>\fIname\fR, \fB\-class\fR=>\fIclass\fR);" 4
.IX Item "$widget->widgetClass(Name=>name, -class=>class);"
Identify a new widget with \fIname\fR and/or \fIclass\fR.
\&\fBName\fR specifies the path element for the widget; names generally begin with a
lowercase letter.  \fB\-class\fR 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 \fBMainWindow\fR widgets have a default class, made by uppercasing the
first letter of the application name.
.ie n .IP \fR\fI$widget\fR\fI\fR\->\fBPathName\fR; 4
.el .IP \fR\f(CI$widget\fR\fI\fR\->\fBPathName\fR; 4
.IX Item "$widget->PathName;"
The \fBPathName\fR method returns the widget's \fIpathname\fR, which uniquely
identifies the widget within the application.
.ie n .IP "\fR\fI$widget\fR\fI\fR\->\fBoptionAdd\fR(\fIpattern\fR=>\fIvalue \fR?, \fIpriority\fR?);" 4
.el .IP "\fR\f(CI$widget\fR\fI\fR\->\fBoptionAdd\fR(\fIpattern\fR=>\fIvalue \fR?, \fIpriority\fR?);" 4
.IX Item "$widget->optionAdd(pattern=>value ?, priority?);"
The \fBoptionAdd\fR method adds a new option to the database.
\&\fIPattern\fR contains the option being specified, and consists of
names and/or classes separated by asterisks or dots, in the usual
X format.  \fIValue\fR contains a text string to associate with
\&\fIpattern\fR; this is the value that will be returned in calls to
the \fBoptionGet\fR method.  If \fIpriority\fR is specified, it indicates
the priority level for this option (see below for legal values);
it defaults to \fBinteractive\fR. This method always returns an empty
string.
.ie n .IP \fR\fI$widget\fR\fI\fR\->\fBoptionClear\fR; 4
.el .IP \fR\f(CI$widget\fR\fI\fR\->\fBoptionClear\fR; 4
.IX Item "$widget->optionClear;"
The \fBoptionClear\fR method clears the option database.  Default
options (from the \fBRESOURCE_MANAGER\fR property or the \fB.Xdefaults\fR
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.
.ie n .IP \fR\fI$widget\fR\fI\fR\->\fBoptionGet\fR(\fIname,class\fR); 4
.el .IP \fR\f(CI$widget\fR\fI\fR\->\fBoptionGet\fR(\fIname,class\fR); 4
.IX Item "$widget->optionGet(name,class);"
The \fBoptionGet\fR method returns the value of the option specified for
\&\fR\f(CI$widget\fR\fI\fR under \fIname\fR and \fIclass\fR.  To look up the option,
\&\fBoptionGet\fR matches the patterns in the resource database against
\&\fI\fR\f(CI$widget\fR\fI\fR's \fIpathname\fR along with the class of \fI\fR\f(CI$widget\fR\fI\fR
(or its parent if \fI\fR\f(CI$widget\fR\fI\fR 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 \fBMainWindow\fR's name
is the \fBappname\fR and its class is (by default) derived from the name
of the script.
.Sp
If several entries in the option database match \fR\f(CI$widget\fR\fI\fR's \fIpathname\fR,
\&\fIname\fR, and \fIclass\fR, then the method returns whichever was created with
highest \fIpriority\fR level.  If there are several matching
entries at the same priority level, then it returns whichever entry
was \fImost recently entered\fR into the option database.  If there are
no matching entries, then the empty string is returned.
.ie n .IP \fR\fI$widget\fR\fI\fR\->\fBoptionReadfile\fR(\fIfileName\fR?,\fIpriority\fR?); 4
.el .IP \fR\f(CI$widget\fR\fI\fR\->\fBoptionReadfile\fR(\fIfileName\fR?,\fIpriority\fR?); 4
.IX Item "$widget->optionReadfile(fileName?,priority?);"
The \fBoptionReadfile\fR method reads \fIfileName\fR, which should have the
standard format for an X resource database such as \fB.Xdefaults\fR, and
adds all the options specified in that file to the option database.
If \fIpriority\fR is specified, it indicates the priority level at which
to enter the options;  \fIpriority\fR defaults to \fBinteractive\fR.
.Sp
The \fIpriority\fR arguments to the \fBoption\fR methods are
normally specified symbolically using one of the following values:
.RS 4
.IP \fBwidgetDefault\fR 8
.IX Item "widgetDefault"
Level 20.  Used for default values hard-coded into widgets.
.IP \fBstartupFile\fR 8
.IX Item "startupFile"
Level 40.  Used for options specified in application-specific
startup files.
.IP \fBuserDefault\fR 8
.IX Item "userDefault"
Level 60.  Used for options specified in user-specific defaults
files, such as \fB.Xdefaults\fR, resource databases loaded into
the X server, or user-specific startup files.
.IP \fBinteractive\fR 8
.IX Item "interactive"
Level 80.  Used for options specified interactively after the application
starts running.  If \fIpriority\fR isn't specified, it defaults to
this level.
.RE
.RS 4
.Sp
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.
.RE
.SH BUGS
.IX Header "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 \fBxrdb \-merge\fR can change the order.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Tk::Xrm
.SH KEYWORDS
.IX Header "KEYWORDS"
database, option, priority, retrieve