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

FreeBSD Manual Pages

  
 
  

home | help
ConfigSpecs(3)	      User Contributed Perl Documentation	ConfigSpecs(3)

NAME
       Tk::ConfigSpecs - Defining behaviour of 'configure' for composite
       widgets.

SYNOPSIS
	   sub Populate
	   {
	    my ($composite,$args) = @_;
	    ...
	    $composite->ConfigSpecs('-attribute' => [ where,dbName,dbClass,default ]);
	    $composite->ConfigSpecs('-alias' =>	'-otherattribute');
	    $composite->ConfigSpecs('DEFAULT' => [ where ]);
	    $composite->ConfigSpecs($subwidget->ConfigSpecs);
	    ...
	   }

	   $composite->configure(-attribute => value);

DESCRIPTION
       The aim is to make the composite	widget configure method	look as	much
       like a regular Tk widget's configure as possible.  (See Tk::options for
       a description of	this behaviour.)  To enable this the attributes	that
       the composite as	a whole	accepts	needs to be defined.

   Defining the	ConfigSpecs for	a class.
       Typically a widget will have one	or more	calls like the following

	   $composite->ConfigSpecs(-attribute => [where,dbName,dbClass,default]);

       in its Populate method. When ConfigSpecs	is called this way (with
       arguments) the arguments	are used to construct or augment/replace a
       hash table for the widget. (More	than one -option=>value	pair can be
       specified to a single call.)

       dbName, dbClass and default are only used by ConfigDefault described
       below, or to respond to 'inquiry' configure commands.

       It may be either	one of the values below, or a list of such values
       enclosed	in [].

       The currently permitted values of where are:

       'ADVERTISED'
	   Apply configure to advertised subwidgets.

       'DESCENDANTS'
	   Apply configure recursively to all descendants.

       'CALLBACK'
	   Setting the attribute does "Tk::Callback->new($value)" before
	   storing in "$composite->{Configure}{-attribute}". This is
	   appropriate for "-command =>	..." attributes	that are handled by
	   the composite and not forwarded to a	subwidget. (E.g. Tk::Tiler has
	   "-yscrollcommand" to	allow it to have scrollbar attached.)

	   This	may be the first of several 'validating' keywords (e.g.	font,
	   cursor, anchor etc.)	that core Tk makes special for C code.

       'CHILDREN'
	   Apply configure to all children.  (Children are the immediate
	   descendants of a widget.)

       'METHOD'
	   Call	"$cw->attribute(value)"

	   This	is the most general case. Simply have a	method of the
	   composite class with	the same name as the attribute.	 The method
	   may do any validation and have whatever side-effects	you like.  (It
	   is probably worth 'queueing'	using afterIdle	for more complex side-
	   effects.)

       'PASSIVE'
	   Simply store	value in "$composite->{Configure}{-attribute}".

	   This	form is	also a useful placeholder for attributes which you
	   currently only handle at create time.

       'SELF'
	   Apply configure to the core widget (e.g. Frame) that	is the basis
	   of the composite. (This is the default behaviour for	most
	   attributes which makes a simple Frame behave	the way	you would
	   expect.) Note that once you have specified ConfigSpecs for an
	   attribute you must explicitly include 'SELF'	in the list if you
	   want	the attribute to apply to the composite	itself (this avoids
	   nasty infinite recursion problems).

       $reference (blessed)
	   Call	$reference->configure(-attribute => value)

	   A common case is where $reference is	a subwidget.

	   $reference may also be result of

		Tk::Config->new(setmethod,getmethod,args,...);

	   Tk::Config class is used to implement all the above keyword types.
	   The class has "configure" and "cget"	methods	so allows higher level
	   code	to always just call one	of those methods on an object of some
	   kind.

       hash reference
	   Defining:

		   $cw->ConfigSpecs(
			   ...
			   -option => [	{ -optionX=>$w1, -optionY=>[$w2, $w3] },
					   dbname dbclass default ],
			   ...
			   );

	   So "$cw->configure(-option => value)" actually does

		   $w1->configure(-optionX => value);
		   $w2->configure(-optionY => value);
		   $w3->configure(-optionY => value);

       'otherstring'
	   Call

	       $composite->Subwidget('otherstring')->configure(	-attribute => value );

	   While this is here for backward compatibility with Tk-b5, it	is
	   probably better just	to use the subwidget reference directly.  The
	   only	case for retaining this	form is	to allow an additional layer
	   of abstraction - perhaps having a 'current' subwidget - this	is
	   unproven.

       Aliases
	   "ConfigSpecs( -alias	=> '-otherattribute' )"	is used	to make
	   "-alias" equivalent to "-otherattribute". For example the aliases

	       -fg => '-foreground',
	       -bg => '-background'

	   are provided	automatically (if not already specified).

   Delegating all options of a widget class to a subwidget
	   $composite->ConfigSpecs($subwidget->ConfigSpecs);

       The above generates a list of composite ConfigSpecs arguments, one for
       each valid option in $subwidget's class,	and delegates said option to
       $subwidget.  See	Tk::Widget and the widget method ConfigSpecs.
       Duplicating composite ConfigSpecs and widget ConfigSpecs	keys will
       yield undefined results.

   Default values
       When the	Populate method	returns	ConfigDefault is called.  This calls

	   $composite->ConfigSpecs;

       (with no	arguments) to return a reference to a hash. Entries in the
       hash take the form:

	   '-attribute'	=> [ where, dbName, dbClass, default ]

       ConfigDefault ignores 'where' completely	(and also the DEFAULT entry)
       and checks the 'options'	database on the	widget's behalf, and if	an
       entry is	present	matching dbName/dbClass

	   -attribute => value

       is added	to the list of options that new	will eventually	apply to the
       widget. Likewise	if there is not	a match	and default is defined this
       default value will be added.

       Alias entries in	the hash are used to convert user-specified values for
       the alias into values for the real attribute.

   New()-time configure
       Once control returns to new, the	list of	user-supplied options
       augmented by those from ConfigDefault are applied to the	widget using
       the configure method below.

       Widgets are most	flexible and most Tk-like if they handle the majority
       of their	attributes this	way.

   Configuring composites
       Once the	above have occurred calls of the form:

	   $composite->configure( -attribute =>	value );

       should behave like any other widget as far as end-user code is
       concerned.  configure will be handled by	Tk::Derived::configure as
       follows:

	   $composite->ConfigSpecs;

       is called (with no arguments) to	return a reference to a	hash
       -attribute is looked up in this hash, if	-attribute is not present in
       the hash	then 'DEFAULT' is looked for instead.  (Aliases	are tried as
       well and	cause redirection to the aliased attribute).  The result
       should be a reference to	a list like:

	 [ where, dbName, dbClass, default ]

       at this stage only where	is of interest,	it maps	to a list of object
       references (maybe only one) foreach one

	  $object->configure( -attribute => value );

       is evaled.

   Inquiring attributes	of composites
	  $composite->cget( '-attribute' );

       This is handled by  Tk::Derived::cget in	a similar manner to configure.
       At present if where is a	list of	more than one object it	is ignored
       completely and the "cached" value in

	  $composite->{Configure}{-attribute}.

       is returned.

CAVEATS
       The "-background" and "-foreground" option values are automatically
       propagated down to all composite	widget's children. This	may be
       sometimes not desirable,	especially if some subwidgets should use own
       color schemes, either by	using explicit options or by option database
       definitions. If this is the case, then just add

	   -foreground => 'SELF',
	   -background => 'SELF',

       to "ConfigSpecs".

       It is the author's intention to port as many of the "Tix" composite
       widgets as make sense. The mechanism described above may	have to	evolve
       in order	to make	this possible, although	now aliases are	handled	I
       think the above is sufficient.

SEE ALSO
       Tk::composite, Tk::options, Tk::Widget

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

NAME | SYNOPSIS | DESCRIPTION | CAVEATS | SEE ALSO

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

home | help