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