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