1#  Copyright (c) 1990 The Regents of the University of California.
2#  Copyright (c) 1994-1996 Sun Microsystems, Inc.
3#  See the file "license.terms" for information on usage and redistribution
4#  of this file, and for a DISCLAIMER OF ALL WARRANTIES.
5#
6#
7
8=head1 NAME
9
10Tk::option - Using the option database in Perl/Tk
11
12=for category Creating and Configuring Widgets
13
14=head1 SYNOPSIS
15
16S<    >I<$widget>-E<gt>B<widgetClass>(B<Name>=E<gt>I<name>, B<-class>=E<gt>I<class>);
17
18S<    >I<$widget>-E<gt>B<PathName>;
19
20S<    >I<$widget>-E<gt>B<optionAdd>(I<pattern>=E<gt>I<value > ?,I<priority>?);
21
22S<    >I<$widget>-E<gt>B<optionClear>;
23
24S<    >I<$widget>-E<gt>B<optionGet>(I<name, class>);
25
26S<    >I<$widget>-E<gt>B<optionReadfile>(I<fileName> ?,I<priority>?);
27
28=head1 DESCRIPTION
29
30The option database (also known as the I<resource database> or the
31I<application defaults database>) is a set of rules for applying
32default options to widgets.  Users and system administrators can
33set up these rules to customize the appearance of applications
34without changing any application code; for example, a user might
35set up personal foreground and background colors, or a site
36might use fonts associated with visual or language preferences.
37Different window managers (and implementations of them) have implemented
38the database differently, but most Xt-based window managers use the
39I<.Xdefaults> file or the I<xrdb> utility to manage user preferences;
40some use both, and/or implement a more complex set of site, user and
41application databases.  Check your site documentation for these topics
42or your window manager's B<RESOURCE_MANAGER> property.
43
44=head2 Being a good citizen
45
46For most applications, the option database "just works."  The B<option...>
47methods are for applications that need to do something unusual, such as
48add new rules or test an option's default.  Even in such cases, the
49application should provide for user preferences.
50Do not hardcode widget options without a B<very> good reason.
51All users have their own tastes and they are all different.
52They choose a special font in a special size and have often spend a
53lot of time working out a color scheme that they will love until death.
54When you respect their choices they will enjoy working with your
55applications much more.  Don't destroy the common look and feel of a
56personal desktop.
57
58=head2 Option rules and widget identification
59
60All widgets in an application are identified hierarchically by I<pathname>,
61starting from the B<MainWindow> and passing through each widget used to create
62the endpoint.  The path elements are I<widget names>, much like the elements
63of a file path from the root directory to a file.  The rules in the option
64database are patterns that are matched against a widget's I<pathname> to
65determine which defaults apply.
66When a widget is created, the B<Name> option can be
67used to assign the widget's name and thus create a distinctive path
68for widgets in an application.  If the B<Name> option isn't given,
69Perl/Tk assigns a default name based on the type of widget; a
70B<MainWindow>'s default name is the B<appname>.  These defaults are fine
71for most widgets, so don't feel you need to find a meaningful name for
72every widget you create.
73A widget must have a distinctive name to allow users to tailor its
74options independently of other widgets in an application.  For instance,
75to create a B<Text> widget that will
76have special options assigned to it, give it a name such as:
77
78  $text = $mw->Text(Name => 'importantText');
79
80You can then tailor the widget's attributes with a rule in the option
81database such as:
82
83  *importantText*foreground: red
84
85The I<class> attribute identifies groups of widgets, usually within an
86application but also to group similar widgets among different applications.
87One typically assigns a class to a B<TopLevel> or B<Frame> so that the
88class will apply to all of that widget's children.  To extend the example,
89we could be more specific about the importantText widget
90by giving its frame a class:
91
92  $frame = $mw->Frame(-class => 'Urgent');
93  $text = $frame->Text(Name => 'importantText');
94
95Then the resource pattern can be specified as so:
96
97  *Urgent*importantText*foreground: red
98
99Similarly, the pattern C<*Urgent*background: cyan> would apply to all
100widgets in the frame.
101
102=head1 METHODS
103
104=over 4
105
106=item I<$widget>-E<gt>B<widgetClass>(B<Name>=E<gt>I<name>, B<-class>=E<gt>I<class>);
107
108Identify a new widget with I<name> and/or I<class>.
109B<Name> specifies the path element for the widget; names generally begin with a
110lowercase letter.  B<-class> specifies the class for the widget and its
111children; classes generally begin with an uppercase letter.
112If not specified, Perl/Tk will assign a unique default name to each widget.
113Only B<MainWindow> widgets have a default class, made by uppercasing the
114first letter of the application name.
115
116=item I<$widget>-E<gt>B<PathName>;
117
118The B<PathName> method returns the widget's I<pathname>, which uniquely
119identifies the widget within the application.
120
121=item I<$widget>-E<gt>B<optionAdd>(I<pattern>=E<gt>I<value >?, I<priority>?);
122
123The B<optionAdd> method adds a new option to the database.
124I<Pattern> contains the option being specified, and consists of
125names and/or classes separated by asterisks or dots, in the usual
126X format.  I<Value> contains a text string to associate with
127I<pattern>; this is the value that will be returned in calls to
128the B<optionGet> method.  If I<priority> is specified, it indicates
129the priority level for this option (see below for legal values);
130it defaults to B<interactive>. This method always returns an empty
131string.
132
133=item I<$widget>-E<gt>B<optionClear>;
134
135The B<optionClear> method clears the option database.  Default
136options (from the B<RESOURCE_MANAGER> property or the B<.Xdefaults>
137file) will be reloaded automatically the next time an option is
138added to the database or removed from it.  This method always returns
139an empty string.
140
141=item I<$widget>-E<gt>B<optionGet>(I<name,class>);
142
143The B<optionGet> method returns the value of the option specified for
144I<$widget> under I<name> and I<class>.  To look up the option,
145B<optionGet> matches the patterns in the resource database against
146I<$widget>'s I<pathname> along with the class of I<$widget>
147(or its parent if I<$widget> has no class specified).  The widget's
148class and name are options set when the widget is created (not
149related to class in the sense of L<bless>); the B<MainWindow>'s name
150is the B<appname> and its class is (by default) derived from the name
151of the script.
152
153If several entries in the option database match I<$widget>'s I<pathname>,
154I<name>, and I<class>, then the method returns whichever was created with
155highest I<priority> level.  If there are several matching
156entries at the same priority level, then it returns whichever entry
157was I<most recently entered> into the option database.  If there are
158no matching entries, then the empty string is returned.
159
160=item I<$widget>-E<gt>B<optionReadfile>(I<fileName>?,I<priority>?);
161
162The B<optionReadfile> method reads I<fileName>, which should have the
163standard format for an X resource database such as B<.Xdefaults>, and
164adds all the options specified in that file to the option database.
165If I<priority> is specified, it indicates the priority level at which
166to enter the options;  I<priority> defaults to B<interactive>.
167
168The I<priority> arguments to the B<option> methods are
169normally specified symbolically using one of the following values:
170
171=over 8
172
173=item B<widgetDefault>
174
175Level 20.  Used for default values hard-coded into widgets.
176
177=item B<startupFile>
178
179Level 40.  Used for options specified in application-specific
180startup files.
181
182=item B<userDefault>
183
184Level 60.  Used for options specified in user-specific defaults
185files, such as B<.Xdefaults>, resource databases loaded into
186the X server, or user-specific startup files.
187
188=item B<interactive>
189
190Level 80.  Used for options specified interactively after the application
191starts running.  If I<priority> isn't specified, it defaults to
192this level.
193
194=back
195
196Any of the above keywords may be abbreviated.  In addition, priorities
197may be specified numerically using integers between 0 and 100,
198inclusive.  The numeric form is probably a bad idea except for new priority
199levels other than the ones given above.
200
201=back
202
203=head1 BUGS
204
205The priority scheme used by core Tk is not the same as used by normal Xlib
206routines. In particular is assumes that the order of the entries is defined,
207but user commands like B<xrdb -merge> can change the order.
208
209=head1 SEE ALSO
210
211L<Tk::Xrm|Tk::Xrm>
212
213=head1 KEYWORDS
214
215database, option, priority, retrieve
216
217=cut
218