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

NAME

6       Tk::CmdLine - Process standard X11 command line options and set initial
7       resources
8

SYNOPSIS

10         Tk::CmdLine::SetArguments([@argument]);
11
12         my $value = Tk::CmdLine::cget([$option]);
13
14         Tk::CmdLine::SetResources((\@resource | $resource) [, $priority]);
15
16         Tk::CmdLine::LoadResources(
17             [ -symbol   => $symbol     ]
18             [ -file     => $fileSpec   ]
19             [ -priority => $priority   ]
20             [ -echo     => $fileHandle ] );
21

DESCRIPTION

23       Process standard X11 command line options and set initial resources.
24
25       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
31       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
36   Command Line Options
37       -background Color | -bg Color
38           Specifies the color to be used for the window background.
39
40       -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
46       -display Display | -screen Display
47           Specifies the name of the X server to be used.
48
49       -font Font | -fn Font
50           Specifies the font to be used for displaying text.
51
52       -foreground Color | -fg Color
53           Specifies the color to be used for text or graphics.
54
55       -geometry Geometry
56           Specifies the initial size and location of the first MainWindow.
57
58       -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
64       -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
70       -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
76       -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
84       -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
89       -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
94           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
100   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
108       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
113       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
119       User Application Defaults Files
120           User application defaults files may be specified via environment
121           variables $"XUSERFILESEARCHPATH", $"XAPPLRESDIR" or $"HOME".
122

METHODS

124       SetArguments - Tk::CmdLine::SetArguments([@argument])
125           Extract the X11 options contained in a specified array (@ARGV by
126           default).
127
128             Tk::CmdLine::SetArguments([@argument])
129
130           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
136           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
140       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
145       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
150             Tk::CmdLine::cget([$option])
151
152           The valid options are: -class, -name, -screen and -title.  If no
153           option is specified, -class is implied.
154
155           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
159             my $class = Tk::CmdLine::cget(); # process command line and return class
160
161       SetResources - Tk::CmdLine::SetResources((\@resource | $resource) [,
162       $priority])
163           Set the initial resources.
164
165             Tk::CmdLine::SetResources((\@resource | $resource) [, $priority])
166
167           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
174           Note that "SetResources"() first invokes "SetArguments"() if it has
175           not already been invoked.
176
177       LoadResources - Tk::CmdLine::LoadResources([%options])
178           Load initial resources from one or more files.
179
180             Tk::CmdLine::LoadResources(
181                 [ -symbol   => $symbol     ]
182                 [ -file     => $fileSpec   ]
183                 [ -priority => $priority   ]
184                 [ -echo     => $fileHandle ] );
185
186           [ -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
193           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
199           Each file pattern, after substitutions are applied, is assumed to
200           define a FileSpec to be examined.
201
202           When a directory is specified, FileSpecs <DIRECTORY>/<LANG>/<CLASS>
203           and <DIRECTORY>/<CLASS> are defined, in that order.
204
205           [ -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
209           [ -priority => $priority ] specifies the priority, as defined in
210           option, to be associated with the resources (default: userDefault).
211
212           [ -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
216           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
224           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
229           Note that "LoadResources"() first invokes "SetArguments"() if it
230           has not already been invoked.
231

NOTES

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

EXAMPLES

241       1.  @ARGV is processed by Tk::CmdLine at MainWindow creation.
242
243             use Tk;
244
245             # <Process @ARGV - ignoring all X11-specific options>
246
247             my $mw = MainWindow->new();
248
249             MainLoop();
250
251       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
255             use Tk;
256
257             Tk::CmdLine::SetArguments(); # Tk::CmdLine->SetArguments() works too
258
259             # <Process @ARGV - not worrying about X11-specific options>
260
261             my $mw = MainWindow->new();
262
263             MainLoop();
264
265       3.  Just like 2) except that default arguments are loaded first.
266
267             use Tk;
268
269             Tk::CmdLine::SetArguments(qw(-name test -iconic));
270             Tk::CmdLine::SetArguments();
271
272             # <Process @ARGV - not worrying about X11-specific options>
273
274             my $mw = MainWindow->new();
275
276             MainLoop();
277
278       4.  @ARGV is processed by Tk::CmdLine before MainWindow creation.
279           Standard resource files are loaded in before MainWindow creation.
280
281             use Tk;
282
283             Tk::CmdLine::SetArguments();
284
285             # <Process @ARGV - not worrying about X11-specific options>
286
287             Tk::CmdLine::LoadResources();
288
289             my $mw = MainWindow->new();
290
291             MainLoop();
292
293       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
297             use Tk;
298
299             Tk::CmdLine::SetArguments();
300
301             # <Process @ARGV - not worrying about X11-specific options>
302
303             Tk::CmdLine::LoadResources(-echo => \*STDOUT,
304                 -priority => 65, -symbol => 'XFILESEARCHPATH' );
305             Tk::CmdLine::LoadResources(-echo => \*STDOUT,
306                 -priority => 75, -symbol => 'XUSERFILESEARCHPATH' );
307
308             my $mw = MainWindow->new();
309
310             MainLoop();
311
312       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
316             use Tk;
317
318             Tk::CmdLine::SetArguments();
319
320             # <Process @ARGV - not worrying about X11-specific options>
321
322             Tk::CmdLine::LoadResources();
323
324             Tk::CmdLine::SetResources( # set a single resource
325                 '*Button*background: red',
326                 'widgetDefault' );
327
328             Tk::CmdLine::SetResources( # set multiple resources
329                 [ '*Button*background: red', '*Button*foreground: blue' ],
330                 'widgetDefault' );
331
332             my $mw = MainWindow->new();
333
334             MainLoop();
335

ENVIRONMENT

337       HOME (optional)
338           Home directory which may contain user application defaults files as
339           $"HOME"/$"LANG"/<CLASS> or $"HOME"/<CLASS>.
340
341       LANG (optional)
342           The current language (default: C).
343
344       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
349       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
354       XAPPLRESDIR (optional)
355           Directory containing user application defaults files as
356           $"XAPPLRESDIR"/$"LANG"/<CLASS> or $"XAPPLRESDIR"/<CLASS>.
357

SEE ALSO

359       MainWindow option
360

HISTORY

362       ·   1999.03.04 Ben Pavon <ben.pavon@hsc.hac.com>
363
364           Rewritten as an object-oriented module.
365
366           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
372           Added the "SetResources"() and "LoadResources"() functions to allow
373           the definition of resources prior to MainWindow creation.
374
375       ·   2000.08.31 Ben Pavon <ben.pavon@hsc.hac.com>
376
377           Added the "GetArguments"() method which returns the list of
378           arguments that have been processed by "SetArguments"().
379
380           Modified "LoadResources"() to split the symbols using the OS-
381           dependent path delimiter defined in the Config module.
382
383           Modified "LoadResources"() to eliminate a warning message when
384           processing patterns %l, %C, %S.
385
386
387
388perl v5.16.3                      2014-06-10                        CmdLine(3)
Impressum