Chip 2000 May

home *** CD-ROM | disk | FTP | other *** search

/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _23b90f6a5b166920c010a1312fef4e85 < prev next >

Wrap

Text File | 2000-03-23 | 11.4 KB | 258 lines

<HTML> <HEAD> <TITLE>Tk::ConfigSpecs - Defining behaviour of 'configure' for composite widgets.</TITLE> <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css"> <LINK REV="made" HREF="mailto:"> </HEAD> <BODY> <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%> <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc"> Tk::ConfigSpecs - Defining behaviour of 'configure' for composite widgets. </TD></TR> </TABLE> <A NAME="__index__"></A>  <UL> <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI> <LI><A HREF="#synopsis">SYNOPSIS</A></LI> <LI><A HREF="#description">DESCRIPTION</A></LI> <UL> <LI><A HREF="#defining the configspecs for a class.">Defining the ConfigSpecs for a class.</A></LI> <LI><A HREF="#default values">Default Values</A></LI> <LI><A HREF="#new()time configure">New()-time Configure</A></LI> <LI><A HREF="#configuring composites">Configuring composites</A></LI> <LI><A HREF="#inquiring attributes of composites">Inquiring attributes of composites</A></LI> </UL> <LI><A HREF="#caveats">CAVEATS</A></LI> <LI><A HREF="#see also">SEE ALSO</A></LI> </UL>  <HR> <H1><A NAME="name">NAME</A></H1> Tk::ConfigSpecs - Defining behaviour of 'configure' for composite widgets. <HR> <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1> <UL> <LI>Linux</LI> <LI>Solaris</LI> <LI>Windows</LI> </UL> <HR> <H1><A NAME="synopsis">SYNOPSIS</A></H1> <PRE> sub Populate { my ($composite,$args) = @_; ... $composite->ConfigSpecs('-attribute' => [ where,dbName,dbClass,default ]); $composite->ConfigSpecs('-alias' => '-otherattribute'); $composite->ConfigSpecs('DEFAULT' => [ where ]); ... }</PRE> <PRE> $composite->configure(-attribute => value);</PRE> <HR> <H1><A NAME="description">DESCRIPTION</A></H1> The aim is to make the composite widget configure method look as much like a regular Tk widget's configure as possible. (See <A HREF="../../../site/lib/Tk/options.html">the Tk::options manpage</A> for a description of this behaviour.) To enable this the attributes that the composite as a whole accepts needs to be defined. <H2><A NAME="defining the configspecs for a class.">Defining the ConfigSpecs for a class.</A></H2> Typically a widget will have one or more calls like the following <PRE> $composite->ConfigSpecs(-attribute => [where,dbName,dbClass,default]);</PRE> 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: <DL> <DT><A NAME="item_%27ADVERTISED%27">'ADVERTISED'</A> <DD> apply configure to advertised subwidgets. <DT><A NAME="item_%27DESCENDANTS%27">'DESCENDANTS'</A> <DD> apply configure recursively to all descendants. <DT><A NAME="item_%27CALLBACK%27">'CALLBACK'</A> <DD> Setting the attribute does <CODE>Tk::Callback->new($value)</CODE> before storing in <CODE>$composite->{Configure}{-attribute}</CODE>. This is appropriate for <CODE>-command => ...</CODE> attributes that are handled by the composite and not forwarded to a subwidget. (E.g. Tk::Tiler has <CODE>-yscrollcommand</CODE> 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. <DT><A NAME="item_%27CHILDREN%27">'CHILDREN'</A> <DD> apply configure to all children. (Children are the immediate descendants of a widget.) <DT><A NAME="item_%27METHOD%27">'METHOD'</A> <DD> Call <CODE>$cw->attribute(value)</CODE> 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.) <DT><A NAME="item_%27PASSIVE%27">'PASSIVE'</A> <DD> Simply store value in <CODE>$composite->{Configure}{-attribute}</CODE>. This form is also a useful placeholder for attributes which you currently only handle at create time. <DT><A NAME="item_%27SELF%27">'SELF'</A> <DD> 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 <A HREF="#item_%27SELF%27"><CODE>'SELF'</CODE></A> in the list if you want the attribute to apply to the composite itself (this avoids nasty infinite recursion problems). <DT><A NAME="item_reference">$reference (blessed)</A> <DD> Call $reference->configure(-attribute => value) A common case is where $reference is a subwidget. $reference may also be result of <PRE> Tk::Config->new(setmethod,getmethod,args,...);</PRE> Tk::Config class is used to implement all the above keyword types. The class has <CODE>configure</CODE> and <CODE>cget</CODE> methods so allows higher level code to always just call one of those methods on an object of some kind. <DT><A NAME="item_hash_reference">hash reference</A> <DD> Defining: <PRE> $cw->ConfigSpecs( ... -option => [ { -optionX=>$w1, -optionY=>[$w2, $w3] }, dbname dbclass default ], ... );</PRE> So <CODE>$cw->configure(-option => value)</CODE> actually does <PRE> $w1->configure(-optionX => value); $w2->configure(-optionY => value); $w3->configure(-optionY => value);</PRE> <DT><A NAME="item_%27otherstring%27">'otherstring'</A> <DD> Call <PRE> $composite->Subwidget('otherstring')->configure( -attribute => value );</PRE> 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. <DT><A NAME="item_Aliases">Aliases</A> <DD> <CODE>ConfigSpecs( -alias => '-otherattribute' )</CODE> is used to make <CODE>-alias</CODE> equivalent to <CODE>-otherattribute</CODE>. For example the aliases <PRE> -fg => '-foreground', -bg => '-background'</PRE> are provided automatically (if not already specified). </DL> <H2><A NAME="default values">Default Values</A></H2> When the Populate method returns ConfigDefault is called. This calls <PRE> $composite->ConfigSpecs;</PRE> (with no arguments) to return a reference to a hash. Entries in the hash take the form: <PRE> '-attribute' => [ where, dbName, dbClass, default ]</PRE> 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 <PRE> -attribute => value</PRE> 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. <H2><A NAME="new()time configure">New()-time Configure</A></H2> 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. <H2><A NAME="configuring composites">Configuring composites</A></H2> Once the above have occurred calls of the form: <PRE> $composite->configure( -attribute => value );</PRE> should behave like any other widget as far as end-user code is concerned. configure will be handled by Tk::Derived::configure as follows: <PRE> $composite->ConfigSpecs;</PRE> 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: <PRE> [ where, dbName, dbClass, default ]</PRE> at this stage only where is of interest, it maps to a list of object references (maybe only one) foreach one <PRE> $object->configure( -attribute => value );</PRE> is evaled. <H2><A NAME="inquiring attributes of composites">Inquiring attributes of composites</A></H2> <PRE> $composite->cget( '-attribute' );</PRE> 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 <PRE> $composite->{Configure}{-attribute}.</PRE> is returned. <HR> <H1><A NAME="caveats">CAVEATS</A></H1> 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. <HR> <H1><A NAME="see also">SEE ALSO</A></H1> <A HREF="../../../site/lib/Tk/composite.html">Tk::composite</A>, <A HREF="../../../site/lib/Tk/options.html">Tk::options</A> <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%> <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc"> Tk::ConfigSpecs - Defining behaviour of 'configure' for composite widgets. </TD></TR> </TABLE> </BODY> </HTML>