Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CmdLine(3)	      User Contributed Perl Documentation	    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 arguments. All applications
       written with the	X Toolkit Intrinsics 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 application-specific resource files) via function
       "LoadResources"().

   Command Line	Options
       -background Color | -bg Color
	   Specifies the color to be used for the window background.

       -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 (<pattern>, <value>) pair	is entered into	the
	   options database with optionAdd (for	each MainWindow	configured),
	   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 application 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 <pattern>:<value>.	 They
       may also	contain	blank lines and	comment	lines (denoted by a !
       character as the	first non-blank	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 list of file
	   patterns (joined using the OS-dependent path	delimiter, e.g.	colon
	   on UNIX).

       User Application	Defaults Files
	   User	application defaults files may be specified via	environment
	   variables $"XUSERFILESEARCHPATH", $"XAPPLRESDIR" or $"HOME".

METHODS
       SetArguments - Tk::CmdLine::SetArguments([@argument])
	   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 "SetArguments"() to do this.

       GetArguments - Tk::CmdLine::GetArguments()
	   Get a list of the X11 options that have been	processed by
	   "SetArguments"().  ("GetArguments"()	first invokes "SetArguments"()
	   if it has not already been invoked.)

       cget - Tk::CmdLine::cget([$option])
	   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 application	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 - Tk::CmdLine::SetResources((\@resource | $resource) [,
       $priority])
	   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 elements 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 - Tk::CmdLine::LoadResources([%options])
	   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 environment
	   variable that, if set, defines a list of one	or more	directories
	   and/or file patterns	(joined	using the OS-dependent path delimiter,
	   e.g.	colon on UNIX).	 $"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 translated into $"LANG". Pattern %T is	translated into	app-
	   defaults. Pattern %N	is translated into the application class name.

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

	   When	a directory is specified, FileSpecs <DIRECTORY>/<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:	\*STDOUT)
	   everytime a file is examined	/ loaded.

	   If no -symbol or -file options are specified, "LoadResources"()
	   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-maintained object	reference which	is
       created as necessary, and which always points to	the last object	used.
       "SetArguments"(), "SetResources"() and "LoadResources"()	return the
       object reference.

EXAMPLES
       1.  @ARGV is processed by Tk::CmdLine at	MainWindow creation.

	     use Tk;

	     # <Process	@ARGV -	ignoring all X11-specific options>

	     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 "SetArguments"()	is invoked.

	     use Tk;

	     Tk::CmdLine::SetArguments(); # Tk::CmdLine->SetArguments()	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 priorities.

	     use Tk;

	     Tk::CmdLine::SetArguments();

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

	     Tk::CmdLine::LoadResources(-echo => \*STDOUT,
		 -priority => 65, -symbol => 'XFILESEARCHPATH' );
	     Tk::CmdLine::LoadResources(-echo => \*STDOUT,
		 -priority => 75, -symbol => 'XUSERFILESEARCHPATH' );

	     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*foreground: 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)
	   List	of FileSpec patterns (joined using the OS-dependent path
	   delimiter, e.g. colon on UNIX) used in defining system application
	   defaults files.

       XUSERFILESEARCHPATH (optional)
	   List	of FileSpec patterns (joined using the OS-dependent path
	   delimiter, e.g. colon on UNIX) used in defining user	application
	   defaults files.

       XAPPLRESDIR (optional)
	   Directory containing	user application defaults files	as
	   $"XAPPLRESDIR"/$"LANG"/<CLASS> or $"XAPPLRESDIR"/<CLASS>.

SEE ALSO
       MainWindow option

HISTORY
       o   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 specified array
	   (@ARGV by default).	Eliminate restrictions on the format and
	   location of the options within the array (previously	the X11
	   options could not be	specified 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	MainWindow creation.

       o   2000.08.31 Ben Pavon	<ben.pavon@hsc.hac.com>

	   Added the "GetArguments"() method which returns the list of
	   arguments that have been processed by "SetArguments"().

	   Modified "LoadResources"() to split the symbols using the OS-
	   dependent path delimiter defined in the Config module.

	   Modified "LoadResources"() to eliminate a warning message when
	   processing patterns %l, %C, %S.

perl v5.32.0			  2013-11-15			    CmdLine(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | NOTES | EXAMPLES | ENVIRONMENT | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tk::CmdLine&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help