cmdline(3)

NAME

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

SYNOPSIS

Tk::CmdLine::SetArguments([@argument]);
my $value = Tk::CmdLine::cget([$option]);
Tk::CmdLine::SetResources((@resource  |  $resource)   [,
$priority]);
Tk::CmdLine::LoadResources(
    [ -symbol   => $symbol     ]
    [ -file     => $fileSpec   ]
    [ -priority => $priority   ]
    [ -echo     => $fileHandle ] );

DESCRIPTION

Process standard X11 command line options and set initial
resources.

The X11R5 man page for X11 says: "Most X programs attempt
to use the same names for command line options and argu
ments. All applications written with the X Toolkit Intrin
sics automatically accept the following options: ...".
This module processes these command line options for
perl/Tk applications using the "SetArguments" function.

This module can optionally be used to load initial
resources explicitly via function "SetResources", or from
specified files (default: the standard X11 applicationspecific resource files) via function "LoadResources".

Command Line Options

-background Color | -bg Color: Specifies the color to be used for the window back
ground.
-class Class: Specifies the class under which resources for the
application should be found. This option is useful in
shell aliases to distinguish between invocations of an
application, without resorting to creating links to
alter the executable file name.
-display Display | -screen Display: Specifies the name of the X server to be used.
-font Font | -fn Font: Specifies the font to be used for displaying text.
-foreground Color | -fg Color: Specifies the color to be used for text or graphics.
-geometry Geometry: Specifies the initial size and location of the first
MainWindow.
-iconic: Indicates that the user would prefer that the
application's windows initially not be visible as if
the windows had been immediately iconified by the
user. Window managers may choose not to honor the
application's request.
-motif: Specifies that the application should adhere as
closely as possible to Motif look-and-feel standards.
For example, active elements such as buttons and
scrollbar sliders will not change color when the
pointer passes over them.
-name Name: Specifies the name under which resources for the
application should be found. This option is useful in
shell aliases to distinguish between invocations of an
application, without resorting to creating links to
alter the executable file name.
-synchronous: Indicates that requests to the X server should be sent
synchronously, instead of asynchronously. Since Xlib
normally buffers requests to the server, errors do do
not necessarily get reported immediately after they
occur. This option turns off the buffering so that the
application can be debugged. It should never be used
with a working program.
-title TitleString: This option specifies the title to be used for this
window. This information is sometimes used by a window
manager to provide some sort of header identifying the
window.
-xrm ResourceString: Specifies a resource pattern and value to override any
defaults. It is also very useful for setting resources
that do not have explicit command line arguments.; The ResourceString is of the form <pattern>:<value>, that is (the first) ':' is used to determine which
part is pattern and which part is value. The (<pat_
tern>, <value>) pair is entered into the options database with optionAdd (for each MainWindow config ured), with interactive priority.
Initial Resources
There are several mechanism for initializing the resource
database to be used by an X11 application. Resources may
be defined in a $"HOME"/.Xdefaults file, a system applica
tion defaults file (e.g.
/usr/lib/X11/app-defaults/<CLASS>), or a user application
defaults file (e.g. $"HOME"/<CLASS>). The Tk::CmdLine
functionality for setting initial resources concerns
itself with the latter two.
Resource files contain data lines of the form <pat_ tern>:<value>. They may also contain blank lines and com ment lines (denoted by a ! character as the first nonblank character). Refer to option for a description of <pattern>:<value>.
System Application Defaults Files: System application defaults files may be specified via
environment variable $"XFILESEARCHPATH" which, if set,
contains a colon-separated list of file patterns.
User Application Defaults Files: User application defaults files may be specified via
environment variables $"XUSERFILESEARCHPATH", $"XAP
PLRESDIR" or $"HOME".

METHODS

SetArguments: Extract the X11 options contained in a specified array
(@ARGV by default).

Tk::CmdLine::SetArguments([@argument]); The X11 options may be specified using a single dash as per the X11 convention, or using two dashes -- as
per the POSIX standard (e.g. -geometry 100x100, -geometry 100x100 or -geometry=100x100). The options may be interspersed with other options or arguments.
A -- by itself terminates option processing.; By default, command line options are extracted from
@ARGV the first time a MainWindow is created. The
Tk::MainWindow constructor indirectly invokes "SetAr
guments" to do this.
cget: Get the value of a configuration option specified via
"SetArguments". ("cget" first invokes "SetArguments"
if it has not already been invoked.)

Tk::CmdLine::cget([$option]); The valid options are: -class, -name, -screen and -title. If no option is specified, -class is implied.; A typical use of "cget" might be to obtain the appli
cation class in order to define the name of a resource
file to be loaded in via "LoadResources".

my $class = Tk::CmdLine::cget(); # process command

line and return class; SetResources
Set the initial resources.

Tk::CmdLine::SetResources((@resource | $resource) [,

$priority])

A single resource may be specified using a string of
the form '<pattern>:<value>'. Multiple resources may be specified by passing an array reference whose ele
ments are either strings of the above form, and/or
anonymous arrays of the form [ <pattern>, <value> ]. The optional second argument specifies the priority,
as defined in option, to be associated with the
resources (default: userDefault).

Note that "SetResources" first invokes "SetArguments"
if it has not already been invoked.; LoadResources
Load initial resources from one or more files.

Tk::CmdLine::LoadResources(
[ -symbol => $symbol ]
[ -file => $fileSpec ]
[ -priority => $priority ]
[ -echo => $fileHandle ] );

[ -symbol => $symbol ] specifies the name of an envi ronment variable that, if set, defines a colon-sepa
rated list of one or more directories and/or file pat
terns. $"XUSERFILESEARCHPATH" is a special case. If
$"XUSERFILESEARCHPATH" is not set, $"XAPPLRESDIR" is
checked instead. If $"XAPPLRESDIR" is not set,
$"HOME" is checked instead.

An item is identified as a file pattern if it contains
one or more /%[A-Za-z]/ patterns. Only patterns %L, %T
and %N are currently recognized. All others are
replaced with the null string. Pattern %L is trans
lated into $"LANG". Pattern %T is translated into appdefaults. Pattern %N is translated into the applica tion class name.

Each file pattern, after substitutions are applied, is
assumed to define a FileSpec to be examined.

When a directory is specified, FileSpecs <DIREC
TORY>/<LANG>/<CLASS> and <DIRECTORY>/<CLASS> are defined, in that order.

[ -file => $fileSpec ] specifies a resource file to be
loaded in. The file is silently skipped if if does
not exist, or if it is not readable.

[ -priority => $priority ] specifies the priority, as defined in option, to be associated with the resources
(default: userDefault).

[ -echo => $fileHandle ] may be used to specify that a
line should be printed to the corresponding FileHandle
(default: TDOUT) everytime a file is examined /
loaded.

If no -symbol or -file options are specified, "Load Resources" processes symbol $"XFILESEARCHPATH" with
priority startupFile and $"XUSERFILESEARCHPATH" with priority userDefault. (Note that $"XFILESEARCHPATH" and $"XUSERFILESEARCHPATH" are supposed to contain
only patterns. $"XAPPLRESDIR" and $"HOME" are supposed
to be a single directory. "LoadResources" does not
check/care whether this is the case.)

For each set of FileSpecs, "LoadResources" examines
each FileSpec to determine if the file exists and is
readable. The first file that meets this criteria is
read in and "SetResources" is invoked.

Note that "LoadResources" first invokes "SetArguments"
if it has not already been invoked.

NOTES

This module is an object-oriented module whose methods can
be invoked as object methods, class methods or regular
functions. This is accomplished via an internally-main
tained object reference which is created as necessary, and
which always points to the last object used. "SetArgu
ments", "SetResources" and "LoadResources" return the
object reference.

EXAMPLES

1 @ARGV is processed by Tk::CmdLine at MainWindow cre: ation.

use Tk;

# <Process @ARGV - ignoring all X11-specific op

tions>

my $mw = MainWindow->new();

MainLoop();; 2 @ARGV is processed by Tk::CmdLine before MainWindow
creation. An @ARGV of (--geometry=100x100 -opt1 a b c
-bg red) is equal to (-opt1 a b c) after "SetArgu
ments" is invoked.

use Tk;

Tk::CmdLine::SetArguments(); # Tk::CmdLine->SetArgu

ments() works too

# <Process @ARGV - not worrying about X11-specific

options>

my $mw = MainWindow->new();

MainLoop();

3 Just like 2) except that default arguments are loaded

first.

use Tk;

Tk::CmdLine::SetArguments(qw(-name test -iconic));
Tk::CmdLine::SetArguments();

# <Process @ARGV - not worrying about X11-specific

options>

my $mw = MainWindow->new();

MainLoop();

4 @ARGV is processed by Tk::CmdLine before MainWindow

creation. Standard resource files are loaded in
before MainWindow creation.

use Tk;

Tk::CmdLine::SetArguments();

# <Process @ARGV - not worrying about X11-specific

options>

Tk::CmdLine::LoadResources();

my $mw = MainWindow->new();

MainLoop();

5 @ARGV is processed by Tk::CmdLine before MainWindow

creation. Standard resource files are loaded in
before MainWindow creation using non-default priori
ties.

use Tk;

Tk::CmdLine::SetArguments();

# <Process @ARGV - not worrying about X11-specific

options>

Tk::CmdLine::LoadResources(-echo => TDOUT,
-priority => 65, -symbol => 'XFILESEARCHPATH' );

Tk::CmdLine::LoadResources(-echo => TDOUT,

-priority => 75, -symbol => 'XUSERFILESEARCH

PATH' );

my $mw = MainWindow->new();

MainLoop();

6 @ARGV is processed by Tk::CmdLine before MainWindow

creation. Standard resource files are loaded in
before MainWindow creation. Individual resources are
also loaded in before MainWindow creation.

use Tk;

Tk::CmdLine::SetArguments();

# <Process @ARGV - not worrying about X11-specific

options>

Tk::CmdLine::LoadResources();

Tk::CmdLine::SetResources( # set a single resource
'*Button*background: red',
'widgetDefault' );

Tk::CmdLine::SetResources( # set multiple resources

[ '*Button*background: red', '*Button*fore

ground: blue' ],
'widgetDefault' );

my $mw = MainWindow->new();

MainLoop();

ENVIRONMENT

HOME (optional): Home directory which may contain user application
defaults files as $"HOME"/$"LANG"/<CLASS> or
$"HOME"/<CLASS>.
LANG (optional): The current language (default: C).
XFILESEARCHPATH (optional): Colon-separated list of FileSpec patterns used in
defining system application defaults files.
XUSERFILESEARCHPATH (optional): Colon-separated list of FileSpec patterns used in
defining user application defaults files.
XAPPLRESDIR (optional): Directory containing user application defaults files
as $"XAPPLRESDIR"/$"LANG"/<CLASS> or $"XAPPLRES
DIR"/<CLASS>.

HISTORY

� 1999.03.04 Ben Pavon <ben.pavon@hsc.hac.com>: Rewritten as an object-oriented module.; Allow one to process command line options in a speci
fied array (@ARGV by default). Eliminate restrictions
on the format and location of the options within the
array (previously the X11 options could not be speci
fied in POSIX format and had to be at the beginning of
the array).; Added the "SetResources" and "LoadResources" functions
to allow the definition of resources prior to MainWin
dow creation.

docs.sk

komplexný repozitár dokumentácie

V sekcií