Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | =head1 NAME |
2 | ||
3 | Tk::CmdLine - Process standard X11 command line options and set initial resources | |
4 | ||
5 | =for pm Tk/CmdLine.pm | |
6 | ||
7 | =for category Creating and Configuring Widgets | |
8 | ||
9 | =head1 SYNOPSIS | |
10 | ||
11 | Tk::CmdLine::SetArguments([@argument]); | |
12 | ||
13 | my $value = Tk::CmdLine::cget([$option]); | |
14 | ||
15 | Tk::CmdLine::SetResources((\@resource | $resource) [, $priority]); | |
16 | ||
17 | Tk::CmdLine::LoadResources( | |
18 | [ -symbol => $symbol ] | |
19 | [ -file => $fileSpec ] | |
20 | [ -priority => $priority ] | |
21 | [ -echo => $fileHandle ] ); | |
22 | ||
23 | =head1 DESCRIPTION | |
24 | ||
25 | Process standard X11 command line options and set initial resources. | |
26 | ||
27 | The X11R5 man page for X11 says: "Most X programs attempt to use the same names | |
28 | for command line options and arguments. All applications written with the | |
29 | X Toolkit Intrinsics automatically accept the following options: ...". | |
30 | This module processes these command line options for perl/Tk applications | |
31 | using the C<SetArguments> function. | |
32 | ||
33 | This module can optionally be used to load initial resources explicitly via | |
34 | function C<SetResources>, or from specified files (default: the standard X11 | |
35 | application-specific resource files) via function C<LoadResources>. | |
36 | ||
37 | =head2 Command Line Options | |
38 | ||
39 | =over 4 | |
40 | ||
41 | =item B<-background> I<Color> | B<-bg> I<Color> | |
42 | ||
43 | Specifies the color to be used for the window background. | |
44 | ||
45 | =item B<-class> I<Class> | |
46 | ||
47 | Specifies the class under which resources for the application should be found. | |
48 | This option is useful in shell aliases to distinguish between invocations | |
49 | of an application, without resorting to creating links to alter the executable | |
50 | file name. | |
51 | ||
52 | =item B<-display> I<Display> | B<-screen> I<Display> | |
53 | ||
54 | Specifies the name of the X server to be used. | |
55 | ||
56 | =item B<-font> I<Font> | B<-fn> I<Font> | |
57 | ||
58 | Specifies the font to be used for displaying text. | |
59 | ||
60 | =item B<-foreground> I<Color> | B<-fg> I<Color> | |
61 | ||
62 | Specifies the color to be used for text or graphics. | |
63 | ||
64 | =item B<-geometry> I<Geometry> | |
65 | ||
66 | Specifies the initial size and location of the I<first> | |
67 | L<MainWindow|Tk::MainWindow>. | |
68 | ||
69 | =item B<-iconic> | |
70 | ||
71 | Indicates that the user would prefer that the application's windows initially | |
72 | not be visible as if the windows had been immediately iconified by the user. | |
73 | Window managers may choose not to honor the application's request. | |
74 | ||
75 | =item B<-motif> | |
76 | ||
77 | Specifies that the application should adhere as closely as possible to Motif | |
78 | look-and-feel standards. For example, active elements such as buttons and | |
79 | scrollbar sliders will not change color when the pointer passes over them. | |
80 | ||
81 | =item B<-name> I<Name> | |
82 | ||
83 | Specifies the name under which resources for the application should be found. | |
84 | This option is useful in shell aliases to distinguish between invocations | |
85 | of an application, without resorting to creating links to alter the executable | |
86 | file name. | |
87 | ||
88 | =item B<-synchronous> | |
89 | ||
90 | Indicates that requests to the X server should be sent synchronously, instead of | |
91 | asynchronously. Since Xlib normally buffers requests to the server, errors do | |
92 | do not necessarily get reported immediately after they occur. This option turns | |
93 | off the buffering so that the application can be debugged. It should never | |
94 | be used with a working program. | |
95 | ||
96 | =item B<-title> I<TitleString> | |
97 | ||
98 | This option specifies the title to be used for this window. This information is | |
99 | sometimes used by a window manager to provide some sort of header identifying | |
100 | the window. | |
101 | ||
102 | =item B<-xrm> I<ResourceString> | |
103 | ||
104 | Specifies a resource pattern and value to override any defaults. It is also | |
105 | very useful for setting resources that do not have explicit command line | |
106 | arguments. | |
107 | ||
108 | The I<ResourceString> is of the form E<lt>I<pattern>E<gt>:E<lt>I<value>E<gt>, | |
109 | that is (the first) ':' is used to determine which part is pattern and which | |
110 | part is value. The (E<lt>I<pattern>E<gt>, E<lt>I<value>E<gt>) pair is entered | |
111 | into the options database with B<optionAdd> (for each | |
112 | L<MainWindow|Tk::MainWindow> configured), with I<interactive> priority. | |
113 | ||
114 | =back | |
115 | ||
116 | =head2 Initial Resources | |
117 | ||
118 | There are several mechanism for initializing the resource database to be used | |
119 | by an X11 application. Resources may be defined in a $C<HOME>/.Xdefaults file, | |
120 | a system application defaults file (e.g. | |
121 | /usr/lib/X11/app-defaults/E<lt>B<CLASS>E<gt>), | |
122 | or a user application defaults file (e.g. $C<HOME>/E<lt>B<CLASS>E<gt>). | |
123 | The Tk::CmdLine functionality for setting initial resources concerns itself | |
124 | with the latter two. | |
125 | ||
126 | Resource files contain data lines of the form | |
127 | E<lt>I<pattern>E<gt>:E<lt>I<value>E<gt>. | |
128 | They may also contain blank lines and comment lines (denoted | |
129 | by a ! character as the first non-blank character). Refer to L<option|Tk::option> | |
130 | for a description of E<lt>I<pattern>E<gt>:E<lt>I<value>E<gt>. | |
131 | ||
132 | =over 4 | |
133 | ||
134 | =item System Application Defaults Files | |
135 | ||
136 | System application defaults files may be specified via environment variable | |
137 | $C<XFILESEARCHPATH> which, if set, contains a colon-separated list of file | |
138 | patterns. | |
139 | ||
140 | =item User Application Defaults Files | |
141 | ||
142 | User application defaults files may be specified via environment variables | |
143 | $C<XUSERFILESEARCHPATH>, $C<XAPPLRESDIR> or $C<HOME>. | |
144 | ||
145 | =back | |
146 | ||
147 | =head1 METHODS | |
148 | ||
149 | =over 4 | |
150 | ||
151 | =item B<SetArguments> | |
152 | ||
153 | Extract the X11 options contained in a specified array (@ARGV by default). | |
154 | ||
155 | Tk::CmdLine::SetArguments([@argument]) | |
156 | ||
157 | The X11 options may be specified using a single dash I<-> as per the X11 | |
158 | convention, or using two dashes I<--> as per the POSIX standard (e.g. | |
159 | B<-geometry> I<100x100>, B<-geometry> I<100x100> or B<-geometry=>I<100x100>). | |
160 | The options may be interspersed with other options or arguments. | |
161 | A I<--> by itself terminates option processing. | |
162 | ||
163 | By default, command line options are extracted from @ARGV the first time | |
164 | a MainWindow is created. The Tk::MainWindow constructor indirectly invokes | |
165 | C<SetArguments> to do this. | |
166 | ||
167 | =item B<cget> | |
168 | ||
169 | Get the value of a configuration option specified via C<SetArguments>. | |
170 | (C<cget> first invokes C<SetArguments> if it has not already been invoked.) | |
171 | ||
172 | Tk::CmdLine::cget([$option]) | |
173 | ||
174 | The valid options are: B<-class>, B<-name>, B<-screen> and B<-title>. | |
175 | If no option is specified, B<-class> is implied. | |
176 | ||
177 | A typical use of C<cget> might be to obtain the application class in order | |
178 | to define the name of a resource file to be loaded in via C<LoadResources>. | |
179 | ||
180 | my $class = Tk::CmdLine::cget(); # process command line and return class | |
181 | ||
182 | =item B<SetResources> | |
183 | ||
184 | Set the initial resources. | |
185 | ||
186 | Tk::CmdLine::SetResources((\@resource | $resource) [, $priority]) | |
187 | ||
188 | A single resource may be specified using a string of the form | |
189 | 'E<lt>I<pattern>E<gt>:E<lt>I<value>E<gt>'. Multiple resources may be specified | |
190 | by passing an array reference whose elements are either strings of the above | |
191 | form, and/or anonymous arrays of the form [ E<lt>I<pattern>E<gt>, | |
192 | E<lt>I<value>E<gt> ]. The optional second argument specifies the priority, | |
193 | as defined in L<option|Tk::option>, to be associated with the resources | |
194 | (default: I<userDefault>). | |
195 | ||
196 | Note that C<SetResources> first invokes C<SetArguments> if it has not already | |
197 | been invoked. | |
198 | ||
199 | =item B<LoadResources> | |
200 | ||
201 | Load initial resources from one or more files. | |
202 | ||
203 | Tk::CmdLine::LoadResources( | |
204 | [ -symbol => $symbol ] | |
205 | [ -file => $fileSpec ] | |
206 | [ -priority => $priority ] | |
207 | [ -echo => $fileHandle ] ); | |
208 | ||
209 | [ B<-symbol> =E<gt> $symbol ] specifies the name of an environment variable | |
210 | that, if set, defines a colon-separated list of one or more directories and/or | |
211 | file patterns. $C<XUSERFILESEARCHPATH> is a special case. | |
212 | If $C<XUSERFILESEARCHPATH> is not set, $C<XAPPLRESDIR> is checked instead. | |
213 | If $C<XAPPLRESDIR> is not set, $C<HOME> is checked instead. | |
214 | ||
215 | An item is identified as a file pattern if it contains one or more /%[A-Za-z]/ | |
216 | patterns. Only patterns B<%L>, B<%T> and B<%N> are currently recognized. All | |
217 | others are replaced with the null string. Pattern B<%L> is translated into | |
218 | $C<LANG>. Pattern B<%T> is translated into I<app-defaults>. Pattern B<%N> is | |
219 | translated into the application class name. | |
220 | ||
221 | Each file pattern, after substitutions are applied, is assumed to define a | |
222 | FileSpec to be examined. | |
223 | ||
224 | When a directory is specified, FileSpecs | |
225 | E<lt>B<DIRECTORY>E<gt>/E<lt>B<LANG>E<gt>/E<lt>B<CLASS>E<gt> | |
226 | and E<lt>B<DIRECTORY>E<gt>/E<lt>B<CLASS>E<gt> are defined, in that order. | |
227 | ||
228 | [ B<-file> =E<gt> $fileSpec ] specifies a resource file to be loaded in. | |
229 | The file is silently skipped if if does not exist, or if it is not readable. | |
230 | ||
231 | [ B<-priority> =E<gt> $priority ] specifies the priority, as defined in | |
232 | L<option|Tk::option>, to be associated with the resources | |
233 | (default: I<userDefault>). | |
234 | ||
235 | [ B<-echo> =E<gt> $fileHandle ] may be used to specify that a line should be | |
236 | printed to the corresponding FileHandle (default: \*STDOUT) everytime a file | |
237 | is examined / loaded. | |
238 | ||
239 | If no B<-symbol> or B<-file> options are specified, C<LoadResources> | |
240 | processes symbol $C<XFILESEARCHPATH> with priority I<startupFile> and | |
241 | $C<XUSERFILESEARCHPATH> with priority I<userDefault>. | |
242 | (Note that $C<XFILESEARCHPATH> and $C<XUSERFILESEARCHPATH> are supposed to | |
243 | contain only patterns. $C<XAPPLRESDIR> and $C<HOME> are supposed to be a single | |
244 | directory. C<LoadResources> does not check/care whether this is the case.) | |
245 | ||
246 | For each set of FileSpecs, C<LoadResources> examines each FileSpec to | |
247 | determine if the file exists and is readable. The first file that meets this | |
248 | criteria is read in and C<SetResources> is invoked. | |
249 | ||
250 | Note that C<LoadResources> first invokes C<SetArguments> if it has not already | |
251 | been invoked. | |
252 | ||
253 | =back | |
254 | ||
255 | =head1 NOTES | |
256 | ||
257 | This module is an object-oriented module whose methods can be invoked as object | |
258 | methods, class methods or regular functions. This is accomplished via an | |
259 | internally-maintained object reference which is created as necessary, and which | |
260 | always points to the last object used. C<SetArguments>, C<SetResources> and | |
261 | C<LoadResources> return the object reference. | |
262 | ||
263 | =head1 EXAMPLES | |
264 | ||
265 | =over | |
266 | ||
267 | =item 1 | |
268 | ||
269 | @ARGV is processed by Tk::CmdLine at MainWindow creation. | |
270 | ||
271 | use Tk; | |
272 | ||
273 | # <Process @ARGV - ignoring all X11-specific options> | |
274 | ||
275 | my $mw = MainWindow->new(); | |
276 | ||
277 | MainLoop(); | |
278 | ||
279 | =item 2 | |
280 | ||
281 | @ARGV is processed by Tk::CmdLine before MainWindow creation. | |
282 | An @ARGV of (--geometry=100x100 -opt1 a b c -bg red) | |
283 | is equal to (-opt1 a b c) after C<SetArguments> is invoked. | |
284 | ||
285 | use Tk; | |
286 | ||
287 | Tk::CmdLine::SetArguments(); # Tk::CmdLine->SetArguments() works too | |
288 | ||
289 | # <Process @ARGV - not worrying about X11-specific options> | |
290 | ||
291 | my $mw = MainWindow->new(); | |
292 | ||
293 | MainLoop(); | |
294 | ||
295 | =item 3 | |
296 | ||
297 | Just like 2) except that default arguments are loaded first. | |
298 | ||
299 | use Tk; | |
300 | ||
301 | Tk::CmdLine::SetArguments(qw(-name test -iconic)); | |
302 | Tk::CmdLine::SetArguments(); | |
303 | ||
304 | # <Process @ARGV - not worrying about X11-specific options> | |
305 | ||
306 | my $mw = MainWindow->new(); | |
307 | ||
308 | MainLoop(); | |
309 | ||
310 | =item 4 | |
311 | ||
312 | @ARGV is processed by Tk::CmdLine before MainWindow creation. | |
313 | Standard resource files are loaded in before MainWindow creation. | |
314 | ||
315 | use Tk; | |
316 | ||
317 | Tk::CmdLine::SetArguments(); | |
318 | ||
319 | # <Process @ARGV - not worrying about X11-specific options> | |
320 | ||
321 | Tk::CmdLine::LoadResources(); | |
322 | ||
323 | my $mw = MainWindow->new(); | |
324 | ||
325 | MainLoop(); | |
326 | ||
327 | =item 5 | |
328 | ||
329 | @ARGV is processed by Tk::CmdLine before MainWindow creation. | |
330 | Standard resource files are loaded in before MainWindow creation | |
331 | using non-default priorities. | |
332 | ||
333 | use Tk; | |
334 | ||
335 | Tk::CmdLine::SetArguments(); | |
336 | ||
337 | # <Process @ARGV - not worrying about X11-specific options> | |
338 | ||
339 | Tk::CmdLine::LoadResources(-echo => \*STDOUT, | |
340 | -priority => 65, -symbol => 'XFILESEARCHPATH' ); | |
341 | Tk::CmdLine::LoadResources(-echo => \*STDOUT, | |
342 | -priority => 75, -symbol => 'XUSERFILESEARCHPATH' ); | |
343 | ||
344 | my $mw = MainWindow->new(); | |
345 | ||
346 | MainLoop(); | |
347 | ||
348 | =item 6 | |
349 | ||
350 | @ARGV is processed by Tk::CmdLine before MainWindow creation. | |
351 | Standard resource files are loaded in before MainWindow creation. | |
352 | Individual resources are also loaded in before MainWindow creation. | |
353 | ||
354 | use Tk; | |
355 | ||
356 | Tk::CmdLine::SetArguments(); | |
357 | ||
358 | # <Process @ARGV - not worrying about X11-specific options> | |
359 | ||
360 | Tk::CmdLine::LoadResources(); | |
361 | ||
362 | Tk::CmdLine::SetResources( # set a single resource | |
363 | '*Button*background: red', | |
364 | 'widgetDefault' ); | |
365 | ||
366 | Tk::CmdLine::SetResources( # set multiple resources | |
367 | [ '*Button*background: red', '*Button*foreground: blue' ], | |
368 | 'widgetDefault' ); | |
369 | ||
370 | my $mw = MainWindow->new(); | |
371 | ||
372 | MainLoop(); | |
373 | ||
374 | =back | |
375 | ||
376 | =head1 ENVIRONMENT | |
377 | ||
378 | =over 4 | |
379 | ||
380 | =item B<HOME> (optional) | |
381 | ||
382 | Home directory which may contain user application defaults files as | |
383 | $C<HOME>/$C<LANG>/E<lt>B<CLASS>E<gt> or $C<HOME>/E<lt>B<CLASS>E<gt>. | |
384 | ||
385 | =item B<LANG> (optional) | |
386 | ||
387 | The current language (default: I<C>). | |
388 | ||
389 | =item B<XFILESEARCHPATH> (optional) | |
390 | ||
391 | Colon-separated list of FileSpec patterns used in defining | |
392 | system application defaults files. | |
393 | ||
394 | =item B<XUSERFILESEARCHPATH> (optional) | |
395 | ||
396 | Colon-separated list of FileSpec patterns used in defining | |
397 | user application defaults files. | |
398 | ||
399 | =item B<XAPPLRESDIR> (optional) | |
400 | ||
401 | Directory containing user application defaults files as | |
402 | $C<XAPPLRESDIR>/$C<LANG>/E<lt>B<CLASS>E<gt> or | |
403 | $C<XAPPLRESDIR>/E<lt>B<CLASS>E<gt>. | |
404 | ||
405 | =back | |
406 | ||
407 | =head1 SEE ALSO | |
408 | ||
409 | L<MainWindow|Tk::MainWindow> | |
410 | L<option|Tk::option> | |
411 | ||
412 | =head1 HISTORY | |
413 | ||
414 | =over 4 | |
415 | ||
416 | =item * | |
417 | ||
418 | 1999.03.04 Ben Pavon E<lt>ben.pavon@hsc.hac.comE<gt> | |
419 | ||
420 | Rewritten as an object-oriented module. | |
421 | ||
422 | Allow one to process command line options in a specified array (@ARGV by default). | |
423 | Eliminate restrictions on the format and location of the options within the array | |
424 | (previously the X11 options could not be specified in POSIX format and had to be | |
425 | at the beginning of the array). | |
426 | ||
427 | Added the C<SetResources> and C<LoadResources> functions to allow the definition | |
428 | of resources prior to MainWindow creation. | |
429 | ||
430 | =back | |
431 | ||
432 | =cut |