1option(3) User Contributed Perl Documentation option(3)
2
6 option - Using the option database in Perl/Tk
7
9 $widget->widgetClass(Name=>name, -class=>class);
10 $widget->PathName;
12 $widget->optionAdd(pattern=>value ?,priority?);
14 $widget->optionClear;
16 $widget->optionGet(name, class);
18 $widget->optionReadfile(fileName ?,priority?);
20
22 The option database (also known as the resource database or the appli‐
23 cation defaults database) is a set of rules for applying default
24 options to widgets. Users and system administrators can set up these
25 rules to customize the appearance of applications without changing any
26 application code; for example, a user might set up personal foreground
27 and background colors, or a site might use fonts associated with visual
28 or language preferences. Different window managers (and implementa‐
29 tions of them) have implemented the database differently, but most Xt-
30 based window managers use the .Xdefaults file or the xrdb utility to
31 manage user preferences; some use both, and/or implement a more complex
32 set of site, user and application databases. Check your site documen‐
33 tation for these topics or your window manager's RESOURCE_MANAGER prop‐
34 erty.
35 Being a good citizen
37 For most applications, the option database "just works." The option...
39 methods are for applications that need to do something unusual, such as
40 add new rules or test an option's default. Even in such cases, the
41 application should provide for user preferences. Do not hardcode wid‐
42 get options without a very good reason. All users have their own
43 tastes and they are all different. They choose a special font in a
44 special size and have often spend a lot of time working out a color
45 scheme that they will love until death. When you respect their choices
46 they will enjoy working with your applications much more. Don't
47 destroy the common look and feel of a personal desktop.
48 Option rules and widget identification
50 All widgets in an application are identified hierarchically by path‐
52 name, starting from the MainWindow and passing through each widget used
53 to create the endpoint. The path elements are widget names, much like
54 the elements of a file path from the root directory to a file. The
55 rules in the option database are patterns that are matched against a
56 widget's pathname to determine which defaults apply. When a widget is
57 created, the Name option can be used to assign the widget's name and
58 thus create a distinctive path for widgets in an application. If the
59 Name option isn't given, Perl/Tk assigns a default name based on the
60 type of widget; a MainWindow's default name is the appname. These
61 defaults are fine for most widgets, so don't feel you need to find a
62 meaningful name for every widget you create. A widget must have a dis‐
63 tinctive name to allow users to tailor its options independently of
64 other widgets in an application. For instance, to create a Text widget
65 that will have special options assigned to it, give it a name such as:
66 $text = $mw->Text(Name => 'importantText');
68 You can then tailor the widget's attributes with a rule in the option
70 database such as:
71 *importantText*foreground: red
73 The class attribute identifies groups of widgets, usually within an
75 application but also to group similar widgets among different applica‐
76 tions. One typically assigns a class to a TopLevel or Frame so that
77 the class will apply to all of that widget's children. To extend the
78 example, we could be more specific about the importantText widget by
79 giving its frame a class:
80 $frame = $mw->Frame(-class => 'Urgent');
82 $text = $frame->Text(Name => 'importantText');
83 Then the resource pattern can be specified as so:
85 *Urgent*importantText*foreground: red
87 Similarly, the pattern "*Urgent*background: cyan" would apply to all
89 widgets in the frame.
90
92 $widget->widgetClass(Name=>name, -class=>class);
93 Identify a new widget with name and/or class. Name specifies the
94 path element for the widget; names generally begin with a lowercase
95 letter. -class specifies the class for the widget and its chil‐
96 dren; classes generally begin with an uppercase letter. If not
97 specified, Perl/Tk will assign a unique default name to each wid‐
98 get. Only MainWindow widgets have a default class, made by upper‐
99 casing the first letter of the application name.
100 $widget->PathName;
102 The PathName method returns the widget's pathname, which uniquely
103 identifies the widget within the application.
104 $widget->optionAdd(pattern=>value ?, priority?);
106 The optionAdd method adds a new option to the database. Pattern
107 contains the option being specified, and consists of names and/or
108 classes separated by asterisks or dots, in the usual X format.
109 Value contains a text string to associate with pattern; this is the
110 value that will be returned in calls to the optionGet method. If
111 priority is specified, it indicates the priority level for this
112 option (see below for legal values); it defaults to interactive.
113 This method always returns an empty string.
114 $widget->optionClear;
116 The optionClear method clears the option database. Default options
117 (from the RESOURCE_MANAGER property or the .Xdefaults file) will be
118 reloaded automatically the next time an option is added to the
119 database or removed from it. This method always returns an empty
120 string.
121 $widget->optionGet(name,class);
123 The optionGet method returns the value of the option specified for
124 $widget under name and class. To look up the option, optionGet
125 matches the patterns in the resource database against $widget's
126 pathname along with the class of $widget (or its parent if $widget
127 has no class specified). The widget's class and name are options
128 set when the widget is created (not related to class in the sense
129 of bless); the MainWindow's name is the appname and its class is
130 (by default) derived from the name of the script.
131 If several entries in the option database match $widget's pathname,
133 name, and class, then the method returns whichever was created with
134 highest priority level. If there are several matching entries at
135 the same priority level, then it returns whichever entry was most
136 recently entered into the option database. If there are no match‐
137 ing entries, then the empty string is returned.
138 $widget->optionReadfile(fileName?,priority?);
140 The optionReadfile method reads fileName, which should have the
141 standard format for an X resource database such as .Xdefaults, and
142 adds all the options specified in that file to the option database.
143 If priority is specified, it indicates the priority level at which
144 to enter the options; priority defaults to interactive.
145 The priority arguments to the option methods are normally specified
147 symbolically using one of the following values:
148 widgetDefault
150 Level 20. Used for default values hard-coded into widgets.
151 startupFile
153 Level 40. Used for options specified in application-spe‐
154 cific startup files.
155 userDefault
157 Level 60. Used for options specified in user-specific
158 defaults files, such as .Xdefaults, resource databases
159 loaded into the X server, or user-specific startup files.
160 interactive
162 Level 80. Used for options specified interactively after
163 the application starts running. If priority isn't speci‐
164 fied, it defaults to this level.
165 Any of the above keywords may be abbreviated. In addition, priori‐
167 ties may be specified numerically using integers between 0 and 100,
168 inclusive. The numeric form is probably a bad idea except for new
169 priority levels other than the ones given above.
170
172 The priority scheme used by core Tk is not the same as used by normal
173 Xlib routines. In particular is assumes that the order of the entries
174 is defined, but user commands like xrdb -merge can change the order.
175
177 Tk::Xrm
178
180 database, option, priority, retrieve
181perl v5.8.8 2008-02-05 option(3)