1option(3)             User Contributed Perl Documentation            option(3)
2
3
4

NAME

6       option - Using the option database in Perl/Tk
7

SYNOPSIS

9           $widget->widgetClass(Name=>name, -class=>class);
10
11           $widget->PathName;
12
13           $widget->optionAdd(pattern=>value  ?,priority?);
14
15           $widget->optionClear;
16
17           $widget->optionGet(name, class);
18
19           $widget->optionReadfile(fileName ?,priority?);
20

DESCRIPTION

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
36   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
48   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
65         $text = $mw->Text(Name => 'importantText');
66
67       You can then tailor the widget's attributes with a rule in the option
68       database such as:
69
70         *importantText*foreground: red
71
72       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
79         $frame = $mw->Frame(-class => 'Urgent');
80         $text = $frame->Text(Name => 'importantText');
81
82       Then the resource pattern can be specified as so:
83
84         *Urgent*importantText*foreground: red
85
86       Similarly, the pattern "*Urgent*background: cyan" would apply to all
87       widgets in the frame.
88

METHODS

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
99       $widget->PathName;
100           The PathName method returns the widget's pathname, which uniquely
101           identifies the widget within the application.
102
103       $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
113       $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
120       $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
130           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
137       $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
144           The priority arguments to the option methods are normally specified
145           symbolically using one of the following values:
146
147           widgetDefault
148                   Level 20.  Used for default values hard-coded into widgets.
149
150           startupFile
151                   Level 40.  Used for options specified in application-
152                   specific startup files.
153
154           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
159           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
164           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

BUGS

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

SEE ALSO

175       Tk::Xrm
176

KEYWORDS

178       database, option, priority, retrieve
179
180
181
182perl v5.12.0                      2010-05-13                         option(3)
Impressum