1CmdLine(3) User Contributed Perl Documentation CmdLine(3)
2
6 Tk::CmdLine - Process standard X11 command line options and set initial
7 resources
8
10 Tk::CmdLine::SetArguments([@argument]);
11 my $value = Tk::CmdLine::cget([$option]);
13 Tk::CmdLine::SetResources((\@resource ⎪ $resource) [, $priority]);
15 Tk::CmdLine::LoadResources(
17 [ -symbol => $symbol ]
18 [ -file => $fileSpec ]
19 [ -priority => $priority ]
20 [ -echo => $fileHandle ] );
21
23 Process standard X11 command line options and set initial resources.
24 The X11R5 man page for X11 says: "Most X programs attempt to use the
26 same names for command line options and arguments. All applications
27 written with the X Toolkit Intrinsics automatically accept the follow‐
28 ing options: ...". This module processes these command line options
29 for perl/Tk applications using the "SetArguments"() function.
30 This module can optionally be used to load initial resources explicitly
32 via function "SetResources"(), or from specified files (default: the
33 standard X11 application-specific resource files) via function "Load‐
34 Resources"().
35 Command Line Options
37 -background Color ⎪ -bg Color
39 Specifies the color to be used for the window background.
40 -class Class
42 Specifies the class under which resources for the application
43 should be found. This option is useful in shell aliases to distin‐
44 guish between invocations of an application, without resorting to
45 creating links to alter the executable file name.
46 -display Display ⎪ -screen Display
48 Specifies the name of the X server to be used.
49 -font Font ⎪ -fn Font
51 Specifies the font to be used for displaying text.
52 -foreground Color ⎪ -fg Color
54 Specifies the color to be used for text or graphics.
55 -geometry Geometry
57 Specifies the initial size and location of the first MainWindow.
58 -iconic
60 Indicates that the user would prefer that the application's windows
61 initially not be visible as if the windows had been immediately
62 iconified by the user. Window managers may choose not to honor the
63 application's request.
64 -motif
66 Specifies that the application should adhere as closely as possible
67 to Motif look-and-feel standards. For example, active elements such
68 as buttons and scrollbar sliders will not change color when the
69 pointer passes over them.
70 -name Name
72 Specifies the name under which resources for the application should
73 be found. This option is useful in shell aliases to distinguish
74 between invocations of an application, without resorting to creat‐
75 ing links to alter the executable file name.
76 -synchronous
78 Indicates that requests to the X server should be sent syn‐
79 chronously, instead of asynchronously. Since Xlib normally buffers
80 requests to the server, errors do do not necessarily get reported
81 immediately after they occur. This option turns off the buffering
82 so that the application can be debugged. It should never be used
83 with a working program.
84 -title TitleString
86 This option specifies the title to be used for this window. This
87 information is sometimes used by a window manager to provide some
88 sort of header identifying the window.
89 -xrm ResourceString
91 Specifies a resource pattern and value to override any defaults. It
92 is also very useful for setting resources that do not have explicit
93 command line arguments.
94 The ResourceString is of the form <pattern>:<value>, that is (the
96 first) ':' is used to determine which part is pattern and which
97 part is value. The (<pattern>, <value>) pair is entered into the
98 options database with optionAdd (for each MainWindow configured),
99 with interactive priority.
100 Initial Resources
102 There are several mechanism for initializing the resource database to
104 be used by an X11 application. Resources may be defined in a
105 $"HOME"/.Xdefaults file, a system application defaults file (e.g.
106 /usr/lib/X11/app-defaults/<CLASS>), or a user application defaults file
107 (e.g. $"HOME"/<CLASS>). The Tk::CmdLine functionality for setting ini‐
108 tial resources concerns itself with the latter two.
109 Resource files contain data lines of the form <pattern>:<value>. They
111 may also contain blank lines and comment lines (denoted by a ! charac‐
112 ter as the first non-blank character). Refer to option for a descrip‐
113 tion of <pattern>:<value>.
114 System Application Defaults Files
116 System application defaults files may be specified via environment
117 variable $"XFILESEARCHPATH" which, if set, contains a list of file
118 patterns (joined using the OS-dependent path delimiter, e.g. colon
119 on UNIX).
120 User Application Defaults Files
122 User application defaults files may be specified via environment
123 variables $"XUSERFILESEARCHPATH", $"XAPPLRESDIR" or $"HOME".
124
126 SetArguments - Tk::CmdLine::SetArguments([@argument])
127 Extract the X11 options contained in a specified array (@ARGV by
128 default).
129 Tk::CmdLine::SetArguments([@argument])
131 The X11 options may be specified using a single dash - as per the
133 X11 convention, or using two dashes -- as per the POSIX standard
134 (e.g. -geometry 100x100, -geometry 100x100 or -geometry=100x100).
135 The options may be interspersed with other options or arguments. A
136 -- by itself terminates option processing.
137 By default, command line options are extracted from @ARGV the first
139 time a MainWindow is created. The Tk::MainWindow constructor indi‐
140 rectly invokes "SetArguments"() to do this.
141 GetArguments - Tk::CmdLine::GetArguments()
143 Get a list of the X11 options that have been processed by "SetArgu‐
144 ments"(). ("GetArguments"() first invokes "SetArguments"() if it
145 has not already been invoked.)
146 cget - Tk::CmdLine::cget([$option])
148 Get the value of a configuration option specified via "SetArgu‐
149 ments"(). ("cget"() first invokes "SetArguments"() if it has not
150 already been invoked.)
151 Tk::CmdLine::cget([$option])
153 The valid options are: -class, -name, -screen and -title. If no
155 option is specified, -class is implied.
156 A typical use of "cget"() might be to obtain the application class
158 in order to define the name of a resource file to be loaded in via
159 "LoadResources"().
160 my $class = Tk::CmdLine::cget(); # process command line and return class
162 SetResources - Tk::CmdLine::SetResources((\@resource ⎪ $resource) [,
164 $priority])
165 Set the initial resources.
166 Tk::CmdLine::SetResources((\@resource ⎪ $resource) [, $priority])
168 A single resource may be specified using a string of the form
170 '<pattern>:<value>'. Multiple resources may be specified by passing
171 an array reference whose elements are either strings of the above
172 form, and/or anonymous arrays of the form [ <pattern>, <value> ].
173 The optional second argument specifies the priority, as defined in
174 option, to be associated with the resources (default: userDefault).
175 Note that "SetResources"() first invokes "SetArguments"() if it has
177 not already been invoked.
178 LoadResources - Tk::CmdLine::LoadResources([%options])
180 Load initial resources from one or more files.
181 Tk::CmdLine::LoadResources(
183 [ -symbol => $symbol ]
184 [ -file => $fileSpec ]
185 [ -priority => $priority ]
186 [ -echo => $fileHandle ] );
187 [ -symbol => $symbol ] specifies the name of an environment vari‐
189 able that, if set, defines a list of one or more directories and/or
190 file patterns (joined using the OS-dependent path delimiter, e.g.
191 colon on UNIX). $"XUSERFILESEARCHPATH" is a special case. If
192 $"XUSERFILESEARCHPATH" is not set, $"XAPPLRESDIR" is checked
193 instead. If $"XAPPLRESDIR" is not set, $"HOME" is checked instead.
194 An item is identified as a file pattern if it contains one or more
196 /%[A-Za-z]/ patterns. Only patterns %L, %T and %N are currently
197 recognized. All others are replaced with the null string. Pattern
198 %L is translated into $"LANG". Pattern %T is translated into app-
199 defaults. Pattern %N is translated into the application class name.
200 Each file pattern, after substitutions are applied, is assumed to
202 define a FileSpec to be examined.
203 When a directory is specified, FileSpecs <DIRECTORY>/<LANG>/<CLASS>
205 and <DIRECTORY>/<CLASS> are defined, in that order.
206 [ -file => $fileSpec ] specifies a resource file to be loaded in.
208 The file is silently skipped if if does not exist, or if it is not
209 readable.
210 [ -priority => $priority ] specifies the priority, as defined in
212 option, to be associated with the resources (default: userDefault).
213 [ -echo => $fileHandle ] may be used to specify that a line should
215 be printed to the corresponding FileHandle (default: \*STDOUT)
216 everytime a file is examined / loaded.
217 If no -symbol or -file options are specified, "LoadResources"()
219 processes symbol $"XFILESEARCHPATH" with priority startupFile and
220 $"XUSERFILESEARCHPATH" with priority userDefault. (Note that
221 $"XFILESEARCHPATH" and $"XUSERFILESEARCHPATH" are supposed to con‐
222 tain only patterns. $"XAPPLRESDIR" and $"HOME" are supposed to be a
223 single directory. "LoadResources"() does not check/care whether
224 this is the case.)
225 For each set of FileSpecs, "LoadResources"() examines each FileSpec
227 to determine if the file exists and is readable. The first file
228 that meets this criteria is read in and "SetResources"() is
229 invoked.
230 Note that "LoadResources"() first invokes "SetArguments"() if it
232 has not already been invoked.
233
235 This module is an object-oriented module whose methods can be invoked
236 as object methods, class methods or regular functions. This is accom‐
237 plished via an internally-maintained object reference which is created
238 as necessary, and which always points to the last object used. "SetAr‐
239 guments"(), "SetResources"() and "LoadResources"() return the object
240 reference.
241
243 1 @ARGV is processed by Tk::CmdLine at MainWindow creation.
244 use Tk;
246 # <Process @ARGV - ignoring all X11-specific options>
248 my $mw = MainWindow->new();
250 MainLoop();
252 2 @ARGV is processed by Tk::CmdLine before MainWindow creation. An
254 @ARGV of (--geometry=100x100 -opt1 a b c -bg red) is equal to
255 (-opt1 a b c) after "SetArguments"() is invoked.
256 use Tk;
258 Tk::CmdLine::SetArguments(); # Tk::CmdLine->SetArguments() works too
260 # <Process @ARGV - not worrying about X11-specific options>
262 my $mw = MainWindow->new();
264 MainLoop();
266 3 Just like 2) except that default arguments are loaded first.
268 use Tk;
270 Tk::CmdLine::SetArguments(qw(-name test -iconic));
272 Tk::CmdLine::SetArguments();
273 # <Process @ARGV - not worrying about X11-specific options>
275 my $mw = MainWindow->new();
277 MainLoop();
279 4 @ARGV is processed by Tk::CmdLine before MainWindow creation.
281 Standard resource files are loaded in before MainWindow creation.
282 use Tk;
284 Tk::CmdLine::SetArguments();
286 # <Process @ARGV - not worrying about X11-specific options>
288 Tk::CmdLine::LoadResources();
290 my $mw = MainWindow->new();
292 MainLoop();
294 5 @ARGV is processed by Tk::CmdLine before MainWindow creation.
296 Standard resource files are loaded in before MainWindow creation
297 using non-default priorities.
298 use Tk;
300 Tk::CmdLine::SetArguments();
302 # <Process @ARGV - not worrying about X11-specific options>
304 Tk::CmdLine::LoadResources(-echo => \*STDOUT,
306 -priority => 65, -symbol => 'XFILESEARCHPATH' );
307 Tk::CmdLine::LoadResources(-echo => \*STDOUT,
308 -priority => 75, -symbol => 'XUSERFILESEARCHPATH' );
309 my $mw = MainWindow->new();
311 MainLoop();
313 6 @ARGV is processed by Tk::CmdLine before MainWindow creation.
315 Standard resource files are loaded in before MainWindow creation.
316 Individual resources are also loaded in before MainWindow creation.
317 use Tk;
319 Tk::CmdLine::SetArguments();
321 # <Process @ARGV - not worrying about X11-specific options>
323 Tk::CmdLine::LoadResources();
325 Tk::CmdLine::SetResources( # set a single resource
327 '*Button*background: red',
328 'widgetDefault' );
329 Tk::CmdLine::SetResources( # set multiple resources
331 [ '*Button*background: red', '*Button*foreground: blue' ],
332 'widgetDefault' );
333 my $mw = MainWindow->new();
335 MainLoop();
337
339 HOME (optional)
340 Home directory which may contain user application defaults files as
341 $"HOME"/$"LANG"/<CLASS> or $"HOME"/<CLASS>.
342 LANG (optional)
344 The current language (default: C).
345 XFILESEARCHPATH (optional)
347 List of FileSpec patterns (joined using the OS-dependent path
348 delimiter, e.g. colon on UNIX) used in defining system application
349 defaults files.
350 XUSERFILESEARCHPATH (optional)
352 List of FileSpec patterns (joined using the OS-dependent path
353 delimiter, e.g. colon on UNIX) used in defining user application
354 defaults files.
355 XAPPLRESDIR (optional)
357 Directory containing user application defaults files as $"XAPPLRES‐
358 DIR"/$"LANG"/<CLASS> or $"XAPPLRESDIR"/<CLASS>.
359
361 MainWindow option
362
364 · 1999.03.04 Ben Pavon <ben.pavon@hsc.hac.com>
365 Rewritten as an object-oriented module.
367 Allow one to process command line options in a specified array
369 (@ARGV by default). Eliminate restrictions on the format and loca‐
370 tion of the options within the array (previously the X11 options
371 could not be specified in POSIX format and had to be at the begin‐
372 ning of the array).
373 Added the "SetResources"() and "LoadResources"() functions to allow
375 the definition of resources prior to MainWindow creation.
376 · 2000.08.31 Ben Pavon <ben.pavon@hsc.hac.com>
378 Added the "GetArguments"() method which returns the list of argu‐
380 ments that have been processed by "SetArguments"().
381 Modified "LoadResources"() to split the symbols using the OS-depen‐
383 dent path delimiter defined in the Config module.
384 Modified "LoadResources"() to eliminate a warning message when pro‐
386 cessing patterns %l, %C, %S.
387perl v5.8.8 2008-02-05 CmdLine(3)