Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / Tk::ConfigSpecs.3

.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CONFIGSPECS 1"
.TH CONFIGSPECS 1 "2000-12-30" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
Tk::ConfigSpecs \- Defining behaviour of 'configure' for composite widgets.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 9
\&    sub Populate
\&    {
\&     my ($composite,$args) = @_;
\&     ...
\&     $composite->ConfigSpecs('-attribute' => [ where,dbName,dbClass,default ]);
\&     $composite->ConfigSpecs('-alias' => '-otherattribute');
\&     $composite->ConfigSpecs('DEFAULT' => [ where ]);
\&     ...
\&    }
.Ve
.PP
.Vb 1
\&    $composite->configure(-attribute => value);
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.Sh "Defining the ConfigSpecs for a class."
.IX Subsection "Defining the ConfigSpecs for a class."
Typically a widget will have one or more calls like the following
.PP
.Vb 1
\&    $composite->ConfigSpecs(-attribute => [where,dbName,dbClass,default]);
.Ve
.PP
in its \fBPopulate\fR method. When \fBConfigSpecs\fR is called this way
(with arguments) the arguments are used to construct or augment/replace
a hash table for the widget. (More than one \fI\-option\fR=>\fIvalue\fR
pair can be specified to a single call.)
.PP
\&\fBdbName\fR, \fBdbClass\fR and default are only used by \fBConfigDefault\fR described
below, or to respond to 'inquiry' configure commands.
.PP
It may be either one of the values below, or a list of such values
enclosed in \fB[]\fR.
.PP
The currently permitted values of \fBwhere\fR are:
.IP "\fB'\s-1ADVERTISED\s0'\fR" 4
.IX Item "'ADVERTISED'"
apply \fBconfigure\fR to \fIadvertised\fR subwidgets.
.IP "\fB'\s-1DESCENDANTS\s0'\fR" 4
.IX Item "'DESCENDANTS'"
apply \fBconfigure\fR recursively to all descendants.
.IP "\fB'\s-1CALLBACK\s0'\fR" 4
.IX Item "'CALLBACK'"
Setting the attribute does \f(CW\*(C`Tk::Callback\->new($value)\*(C'\fR before storing
in \f(CW\*(C`$composite\->{Configure}{\-attribute}\*(C'\fR. This is appropriate for
\&\f(CW\*(C`\-command => ...\*(C'\fR attributes that are handled by the composite and not
forwarded to a subwidget. (E.g. \fBTk::Tiler\fR has \f(CW\*(C`\-yscrollcommand\*(C'\fR to
allow it to have scrollbar attached.)
.Sp
This may be the first of several 'validating' keywords (e.g. font, cursor,
anchor etc.) that core Tk makes special for C code.
.IP "\fB'\s-1CHILDREN\s0'\fR" 4
.IX Item "'CHILDREN'"
apply \fBconfigure\fR to all children.  (Children are the immediate
descendants of a widget.)
.IP "\fB'\s-1METHOD\s0'\fR" 4
.IX Item "'METHOD'"
Call \f(CW\*(C`$cw\->attribute(value)\*(C'\fR
.Sp
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 \fBafterIdle\fR for more complex side\-effects.)
.IP "\fB'\s-1PASSIVE\s0'\fR" 4
.IX Item "'PASSIVE'"
Simply store value in \f(CW\*(C`$composite\->{Configure}{\-attribute}\*(C'\fR.
.Sp
This form is also a useful placeholder for attributes which you
currently only handle at create time.
.IP "\fB'\s-1SELF\s0'\fR" 4
.IX Item "'SELF'"
Apply \fBconfigure\fR to the core widget (e.g. \fBFrame\fR) 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 \fBConfigSpecs\fR for an attribute you must explicitly
include \f(CW'SELF'\fR in the list if you want the attribute to apply to the
composite itself (this avoids nasty infinite recursion problems).
.IP "\fB$reference\fR (blessed)" 4
.IX Item "$reference (blessed)"
Call \fB$reference\fR\->configure(\-attribute => value)
.Sp
A common case is where \fB$reference\fR is a subwidget.
.Sp
$reference may also be result of
.Sp
.Vb 1
\&     Tk::Config->new(setmethod,getmethod,args,...);
.Ve
.Sp
\&\fBTk::Config\fR class is used to implement all the above keyword types.  The
class has \f(CW\*(C`configure\*(C'\fR and \f(CW\*(C`cget\*(C'\fR methods so allows higher level code to
\&\fIalways\fR just call one of those methods on an \fIobject\fR of some kind.
.IP "\fBhash reference\fR" 4
.IX Item "hash reference"
Defining:
.Sp
.Vb 6
\&        $cw->ConfigSpecs(
\&                ...
\&                -option => [ { -optionX=>$w1, -optionY=>[$w2, $w3] },
\&                                dbname dbclass default ],
\&                ...
\&                );
.Ve
.Sp
So \f(CW\*(C`$cw\->configure(\-option => value)\*(C'\fR actually does
.Sp
.Vb 3
\&        $w1->configure(-optionX => value);
\&        $w2->configure(-optionY => value);
\&        $w3->configure(-optionY => value);
.Ve
.IP "\fB'otherstring'\fR" 4
.IX Item "'otherstring'"
Call
.Sp
.Vb 1
\&    $composite->Subwidget('otherstring')->configure( -attribute => value );
.Ve
.Sp
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.
.IP "\fBAliases\fR" 4
.IX Item "Aliases"
\&\f(CW\*(C`ConfigSpecs( \-alias => '\-otherattribute' )\*(C'\fR is used to make \f(CW\*(C`\-alias\*(C'\fR
equivalent to \f(CW\*(C`\-otherattribute\*(C'\fR. For example the aliases
.Sp
.Vb 2
\&    -fg => '-foreground',
\&    -bg => '-background'
.Ve
.Sp
are provided automatically (if not already specified).
.Sh "Default Values"
.IX Subsection "Default Values"
When the \fBPopulate\fR method returns \fBConfigDefault\fR is called.  This calls
.PP
.Vb 1
\&    $composite->ConfigSpecs;
.Ve
.PP
(with no arguments) to return a reference to a hash. Entries in the hash
take the form:
.PP
.Vb 1
\&    '-attribute' => [ where, dbName, dbClass, default ]
.Ve
.PP
\&\fBConfigDefault\fR ignores 'where' completely (and also the \s-1DEFAULT\s0 entry) and
checks the 'options' database on the widget's behalf, and if an entry is
present matching dbName/dbClass
.PP
.Vb 1
\&    -attribute => value
.Ve
.PP
is added to the list of options that \fBnew\fR will eventually apply to the
widget. Likewise if there is not a match and default is defined this
default value will be added.
.PP
Alias entries in the hash are used to convert user-specified values for the
alias into values for the real attribute.
.Sh "\fINew()\fP\-time Configure"
.IX Subsection "New()-time Configure"
Once control returns to \fBnew\fR, the list of user-supplied options
augmented by those from \fBConfigDefault\fR are applied to the widget using the
\&\fBconfigure\fR method below.
.PP
Widgets are most flexible and most Tk-like if they handle the majority of
their attributes this way.
.Sh "Configuring composites"
.IX Subsection "Configuring composites"
Once the above have occurred calls of the form:
.PP
.Vb 1
\&    $composite->configure( -attribute => value );
.Ve
.PP
should behave like any other widget as far as end-user code is concerned.
\&\fBconfigure\fR will be handled by \fBTk::Derived::configure\fR as follows:
.PP
.Vb 1
\&    $composite->ConfigSpecs;
.Ve
.PP
is called (with no arguments) to return a reference to a hash \fB\-attribute\fR is
looked up in this hash, if \fB\-attribute\fR is not present in the hash then
\&\fB'\s-1DEFAULT\s0'\fR 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:
.PP
.Vb 1
\&  [ where, dbName, dbClass, default ]
.Ve
.PP
at this stage only \fIwhere\fR is of interest, it maps to a list of object
references (maybe only one) foreach one
.PP
.Vb 1
\&   $object->configure( -attribute => value );
.Ve
.PP
is \fBeval\fRed.
.Sh "Inquiring attributes of composites"
.IX Subsection "Inquiring attributes of composites"
.Vb 1
\&   $composite->cget( '-attribute' );
.Ve
.PP
This is handled by  \fBTk::Derived::cget\fR in a similar manner to configure. At
present if \fIwhere\fR is a list of more than one object it is ignored completely
and the \*(L"cached\*(R" value in
.PP
.Vb 1
\&   $composite->{Configure}{-attribute}.
.Ve
.PP
is returned.
.SH "CAVEATS"
.IX Header "CAVEATS"
It is the author's intention to port as many of the \*(L"Tix\*(R" 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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Tk::composite,
Tk::options