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
28 following options: ...". This module processes these command line
29 options 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
34 "LoadResources"().
35 Command Line Options
37 -background Color | -bg Color
38 Specifies the color to be used for the window background.
39 -class Class
41 Specifies the class under which resources for the application
42 should be found. This option is useful in shell aliases to
43 distinguish between invocations of an application, without
44 resorting to creating links to alter the executable file name.
45 -display Display | -screen Display
47 Specifies the name of the X server to be used.
48 -font Font | -fn Font
50 Specifies the font to be used for displaying text.
51 -foreground Color | -fg Color
53 Specifies the color to be used for text or graphics.
54 -geometry Geometry
56 Specifies the initial size and location of the first MainWindow.
57 -iconic
59 Indicates that the user would prefer that the application's windows
60 initially not be visible as if the windows had been immediately
61 iconified by the user. Window managers may choose not to honor the
62 application's request.
63 -motif
65 Specifies that the application should adhere as closely as possible
66 to Motif look-and-feel standards. For example, active elements such
67 as buttons and scrollbar sliders will not change color when the
68 pointer passes over them.
69 -name Name
71 Specifies the name under which resources for the application should
72 be found. This option is useful in shell aliases to distinguish
73 between invocations of an application, without resorting to
74 creating links to alter the executable file name.
75 -synchronous
77 Indicates that requests to the X server should be sent
78 synchronously, instead of asynchronously. Since Xlib normally
79 buffers requests to the server, errors do do not necessarily get
80 reported immediately after they occur. This option turns off the
81 buffering so that the application can be debugged. It should never
82 be used with a working program.
83 -title TitleString
85 This option specifies the title to be used for this window. This
86 information is sometimes used by a window manager to provide some
87 sort of header identifying the window.
88 -xrm ResourceString
90 Specifies a resource pattern and value to override any defaults. It
91 is also very useful for setting resources that do not have explicit
92 command line arguments.
93 The ResourceString is of the form <pattern>:<value>, that is (the
95 first) ':' is used to determine which part is pattern and which
96 part is value. The (<pattern>, <value>) pair is entered into the
97 options database with optionAdd (for each MainWindow configured),
98 with interactive priority.
99 Initial Resources
101 There are several mechanism for initializing the resource database to
102 be used by an X11 application. Resources may be defined in a
103 $"HOME"/.Xdefaults file, a system application defaults file (e.g.
104 /usr/lib/X11/app-defaults/<CLASS>), or a user application defaults file
105 (e.g. $"HOME"/<CLASS>). The Tk::CmdLine functionality for setting
106 initial resources concerns itself with the latter two.
107 Resource files contain data lines of the form <pattern>:<value>. They
109 may also contain blank lines and comment lines (denoted by a !
110 character as the first non-blank character). Refer to option for a
111 description of <pattern>:<value>.
112 System Application Defaults Files
114 System application defaults files may be specified via environment
115 variable $"XFILESEARCHPATH" which, if set, contains a list of file
116 patterns (joined using the OS-dependent path delimiter, e.g. colon
117 on UNIX).
118 User Application Defaults Files
120 User application defaults files may be specified via environment
121 variables $"XUSERFILESEARCHPATH", $"XAPPLRESDIR" or $"HOME".
122
124 SetArguments - Tk::CmdLine::SetArguments([@argument])
125 Extract the X11 options contained in a specified array (@ARGV by
126 default).
127 Tk::CmdLine::SetArguments([@argument])
129 The X11 options may be specified using a single dash - as per the
131 X11 convention, or using two dashes -- as per the POSIX standard
132 (e.g. -geometry 100x100, -geometry 100x100 or -geometry=100x100).
133 The options may be interspersed with other options or arguments. A
134 -- by itself terminates option processing.
135 By default, command line options are extracted from @ARGV the first
137 time a MainWindow is created. The Tk::MainWindow constructor
138 indirectly invokes "SetArguments"() to do this.
139 GetArguments - Tk::CmdLine::GetArguments()
141 Get a list of the X11 options that have been processed by
142 "SetArguments"(). ("GetArguments"() first invokes "SetArguments"()
143 if it has not already been invoked.)
144 cget - Tk::CmdLine::cget([$option])
146 Get the value of a configuration option specified via
147 "SetArguments"(). ("cget"() first invokes "SetArguments"() if it
148 has not already been invoked.)
149 Tk::CmdLine::cget([$option])
151 The valid options are: -class, -name, -screen and -title. If no
153 option is specified, -class is implied.
154 A typical use of "cget"() might be to obtain the application class
156 in order to define the name of a resource file to be loaded in via
157 "LoadResources"().
158 my $class = Tk::CmdLine::cget(); # process command line and return class
160 SetResources - Tk::CmdLine::SetResources((\@resource | $resource) [,
162 $priority])
163 Set the initial resources.
164 Tk::CmdLine::SetResources((\@resource | $resource) [, $priority])
166 A single resource may be specified using a string of the form
168 '<pattern>:<value>'. Multiple resources may be specified by passing
169 an array reference whose elements are either strings of the above
170 form, and/or anonymous arrays of the form [ <pattern>, <value> ].
171 The optional second argument specifies the priority, as defined in
172 option, to be associated with the resources (default: userDefault).
173 Note that "SetResources"() first invokes "SetArguments"() if it has
175 not already been invoked.
176 LoadResources - Tk::CmdLine::LoadResources([%options])
178 Load initial resources from one or more files.
179 Tk::CmdLine::LoadResources(
181 [ -symbol => $symbol ]
182 [ -file => $fileSpec ]
183 [ -priority => $priority ]
184 [ -echo => $fileHandle ] );
185 [ -symbol => $symbol ] specifies the name of an environment
187 variable that, if set, defines a list of one or more directories
188 and/or file patterns (joined using the OS-dependent path delimiter,
189 e.g. colon on UNIX). $"XUSERFILESEARCHPATH" is a special case. If
190 $"XUSERFILESEARCHPATH" is not set, $"XAPPLRESDIR" is checked
191 instead. If $"XAPPLRESDIR" is not set, $"HOME" is checked instead.
192 An item is identified as a file pattern if it contains one or more
194 /%[A-Za-z]/ patterns. Only patterns %L, %T and %N are currently
195 recognized. All others are replaced with the null string. Pattern
196 %L is translated into $"LANG". Pattern %T is translated into app-
197 defaults. Pattern %N is translated into the application class name.
198 Each file pattern, after substitutions are applied, is assumed to
200 define a FileSpec to be examined.
201 When a directory is specified, FileSpecs <DIRECTORY>/<LANG>/<CLASS>
203 and <DIRECTORY>/<CLASS> are defined, in that order.
204 [ -file => $fileSpec ] specifies a resource file to be loaded in.
206 The file is silently skipped if if does not exist, or if it is not
207 readable.
208 [ -priority => $priority ] specifies the priority, as defined in
210 option, to be associated with the resources (default: userDefault).
211 [ -echo => $fileHandle ] may be used to specify that a line should
213 be printed to the corresponding FileHandle (default: \*STDOUT)
214 everytime a file is examined / loaded.
215 If no -symbol or -file options are specified, "LoadResources"()
217 processes symbol $"XFILESEARCHPATH" with priority startupFile and
218 $"XUSERFILESEARCHPATH" with priority userDefault. (Note that
219 $"XFILESEARCHPATH" and $"XUSERFILESEARCHPATH" are supposed to
220 contain only patterns. $"XAPPLRESDIR" and $"HOME" are supposed to
221 be a single directory. "LoadResources"() does not check/care
222 whether this is the case.)
223 For each set of FileSpecs, "LoadResources"() examines each FileSpec
225 to determine if the file exists and is readable. The first file
226 that meets this criteria is read in and "SetResources"() is
227 invoked.
228 Note that "LoadResources"() first invokes "SetArguments"() if it
230 has not already been invoked.
231
233 This module is an object-oriented module whose methods can be invoked
234 as object methods, class methods or regular functions. This is
235 accomplished via an internally-maintained object reference which is
236 created as necessary, and which always points to the last object used.
237 "SetArguments"(), "SetResources"() and "LoadResources"() return the
238 object reference.
239
241 1. @ARGV is processed by Tk::CmdLine at MainWindow creation.
242 use Tk;
244 # <Process @ARGV - ignoring all X11-specific options>
246 my $mw = MainWindow->new();
248 MainLoop();
250 2. @ARGV is processed by Tk::CmdLine before MainWindow creation. An
252 @ARGV of (--geometry=100x100 -opt1 a b c -bg red) is equal to
253 (-opt1 a b c) after "SetArguments"() is invoked.
254 use Tk;
256 Tk::CmdLine::SetArguments(); # Tk::CmdLine->SetArguments() works too
258 # <Process @ARGV - not worrying about X11-specific options>
260 my $mw = MainWindow->new();
262 MainLoop();
264 3. Just like 2) except that default arguments are loaded first.
266 use Tk;
268 Tk::CmdLine::SetArguments(qw(-name test -iconic));
270 Tk::CmdLine::SetArguments();
271 # <Process @ARGV - not worrying about X11-specific options>
273 my $mw = MainWindow->new();
275 MainLoop();
277 4. @ARGV is processed by Tk::CmdLine before MainWindow creation.
279 Standard resource files are loaded in before MainWindow creation.
280 use Tk;
282 Tk::CmdLine::SetArguments();
284 # <Process @ARGV - not worrying about X11-specific options>
286 Tk::CmdLine::LoadResources();
288 my $mw = MainWindow->new();
290 MainLoop();
292 5. @ARGV is processed by Tk::CmdLine before MainWindow creation.
294 Standard resource files are loaded in before MainWindow creation
295 using non-default priorities.
296 use Tk;
298 Tk::CmdLine::SetArguments();
300 # <Process @ARGV - not worrying about X11-specific options>
302 Tk::CmdLine::LoadResources(-echo => \*STDOUT,
304 -priority => 65, -symbol => 'XFILESEARCHPATH' );
305 Tk::CmdLine::LoadResources(-echo => \*STDOUT,
306 -priority => 75, -symbol => 'XUSERFILESEARCHPATH' );
307 my $mw = MainWindow->new();
309 MainLoop();
311 6. @ARGV is processed by Tk::CmdLine before MainWindow creation.
313 Standard resource files are loaded in before MainWindow creation.
314 Individual resources are also loaded in before MainWindow creation.
315 use Tk;
317 Tk::CmdLine::SetArguments();
319 # <Process @ARGV - not worrying about X11-specific options>
321 Tk::CmdLine::LoadResources();
323 Tk::CmdLine::SetResources( # set a single resource
325 '*Button*background: red',
326 'widgetDefault' );
327 Tk::CmdLine::SetResources( # set multiple resources
329 [ '*Button*background: red', '*Button*foreground: blue' ],
330 'widgetDefault' );
331 my $mw = MainWindow->new();
333 MainLoop();
335
337 HOME (optional)
338 Home directory which may contain user application defaults files as
339 $"HOME"/$"LANG"/<CLASS> or $"HOME"/<CLASS>.
340 LANG (optional)
342 The current language (default: C).
343 XFILESEARCHPATH (optional)
345 List of FileSpec patterns (joined using the OS-dependent path
346 delimiter, e.g. colon on UNIX) used in defining system application
347 defaults files.
348 XUSERFILESEARCHPATH (optional)
350 List of FileSpec patterns (joined using the OS-dependent path
351 delimiter, e.g. colon on UNIX) used in defining user application
352 defaults files.
353 XAPPLRESDIR (optional)
355 Directory containing user application defaults files as
356 $"XAPPLRESDIR"/$"LANG"/<CLASS> or $"XAPPLRESDIR"/<CLASS>.
357
359 MainWindow option
360
362 · 1999.03.04 Ben Pavon <ben.pavon@hsc.hac.com>
363 Rewritten as an object-oriented module.
365 Allow one to process command line options in a specified array
367 (@ARGV by default). Eliminate restrictions on the format and
368 location of the options within the array (previously the X11
369 options could not be specified in POSIX format and had to be at the
370 beginning of the array).
371 Added the "SetResources"() and "LoadResources"() functions to allow
373 the definition of resources prior to MainWindow creation.
374 · 2000.08.31 Ben Pavon <ben.pavon@hsc.hac.com>
376 Added the "GetArguments"() method which returns the list of
378 arguments that have been processed by "SetArguments"().
379 Modified "LoadResources"() to split the symbols using the OS-
381 dependent path delimiter defined in the Config module.
382 Modified "LoadResources"() to eliminate a warning message when
384 processing patterns %l, %C, %S.
385perl v5.32.0 2020-07-28 CmdLine(3)