Tk::ConfigSpecs(3pm)

1ConfigSpecs(3)        User Contributed Perl Documentation       ConfigSpecs(3)
2
3
4

NAME

6       Tk::ConfigSpecs - Defining behaviour of 'configure' for composite
7       widgets.
8

SYNOPSIS

10           sub Populate
11           {
12            my ($composite,$args) = @_;
13            ...
14            $composite->ConfigSpecs('-attribute' => [ where,dbName,dbClass,default ]);
15            $composite->ConfigSpecs('-alias' => '-otherattribute');
16            $composite->ConfigSpecs('DEFAULT' => [ where ]);
17            $composite->ConfigSpecs($subwidget->ConfigSpecs);
18            ...
19           }
20
21           $composite->configure(-attribute => value);
22

DESCRIPTION

24       The aim is to make the composite widget configure method look as much
25       like a regular Tk widget's configure as possible.  (See Tk::options for
26       a description of this behaviour.)  To enable this the attributes that
27       the composite as a whole accepts needs to be defined.
28
29   Defining the ConfigSpecs for a class.
30       Typically a widget will have one or more calls like the following
31
32           $composite->ConfigSpecs(-attribute => [where,dbName,dbClass,default]);
33
34       in its Populate method. When ConfigSpecs is called this way (with
35       arguments) the arguments are used to construct or augment/replace a
36       hash table for the widget. (More than one -option=>value pair can be
37       specified to a single call.)
38
39       dbName, dbClass and default are only used by ConfigDefault described
40       below, or to respond to 'inquiry' configure commands.
41
42       It may be either one of the values below, or a list of such values
43       enclosed in [].
44
45       The currently permitted values of where are:
46
47       'ADVERTISED'
48           Apply configure to advertised subwidgets.
49
50       'DESCENDANTS'
51           Apply configure recursively to all descendants.
52
53       'CALLBACK'
54           Setting the attribute does "Tk::Callback->new($value)" before
55           storing in "$composite->{Configure}{-attribute}". This is
56           appropriate for "-command => ..." attributes that are handled by
57           the composite and not forwarded to a subwidget. (E.g. Tk::Tiler has
58           "-yscrollcommand" to allow it to have scrollbar attached.)
59
60           This may be the first of several 'validating' keywords (e.g. font,
61           cursor, anchor etc.) that core Tk makes special for C code.
62
63       'CHILDREN'
64           Apply configure to all children.  (Children are the immediate
65           descendants of a widget.)
66
67       'METHOD'
68           Call "$cw->attribute(value)"
69
70           This is the most general case. Simply have a method of the
71           composite class with the same name as the attribute.  The method
72           may do any validation and have whatever side-effects you like.  (It
73           is probably worth 'queueing' using afterIdle for more complex side-
74           effects.)
75
76       'PASSIVE'
77           Simply store value in "$composite->{Configure}{-attribute}".
78
79           This form is also a useful placeholder for attributes which you
80           currently only handle at create time.
81
82       'SELF'
83           Apply configure to the core widget (e.g. Frame) that is the basis
84           of the composite. (This is the default behaviour for most
85           attributes which makes a simple Frame behave the way you would
86           expect.) Note that once you have specified ConfigSpecs for an
87           attribute you must explicitly include 'SELF' in the list if you
88           want the attribute to apply to the composite itself (this avoids
89           nasty infinite recursion problems).
90
91       $reference (blessed)
92           Call $reference->configure(-attribute => value)
93
94           A common case is where $reference is a subwidget.
95
96           $reference may also be result of
97
98                Tk::Config->new(setmethod,getmethod,args,...);
99
100           Tk::Config class is used to implement all the above keyword types.
101           The class has "configure" and "cget" methods so allows higher level
102           code to always just call one of those methods on an object of some
103           kind.
104
105       hash reference
106           Defining:
107
108                   $cw->ConfigSpecs(
109                           ...
110                           -option => [ { -optionX=>$w1, -optionY=>[$w2, $w3] },
111                                           dbname dbclass default ],
112                           ...
113                           );
114
115           So "$cw->configure(-option => value)" actually does
116
117                   $w1->configure(-optionX => value);
118                   $w2->configure(-optionY => value);
119                   $w3->configure(-optionY => value);
120
121       'otherstring'
122           Call
123
124               $composite->Subwidget('otherstring')->configure( -attribute => value );
125
126           While this is here for backward compatibility with Tk-b5, it is
127           probably better just to use the subwidget reference directly.  The
128           only case for retaining this form is to allow an additional layer
129           of abstraction - perhaps having a 'current' subwidget - this is
130           unproven.
131
132       Aliases
133           "ConfigSpecs( -alias => '-otherattribute' )" is used to make
134           "-alias" equivalent to "-otherattribute". For example the aliases
135
136               -fg => '-foreground',
137               -bg => '-background'
138
139           are provided automatically (if not already specified).
140
141   Delegating all options of a widget class to a subwidget
142           $composite->ConfigSpecs($subwidget->ConfigSpecs);
143
144       The above generates a list of composite ConfigSpecs arguments, one for
145       each valid option in $subwidget's class, and delegates said option to
146       $subwidget.  See Tk::Widget and the widget method ConfigSpecs.
147       Duplicating composite ConfigSpecs and widget ConfigSpecs keys will
148       yield undefined results.
149
150   Default values
151       When the Populate method returns ConfigDefault is called.  This calls
152
153           $composite->ConfigSpecs;
154
155       (with no arguments) to return a reference to a hash. Entries in the
156       hash take the form:
157
158           '-attribute' => [ where, dbName, dbClass, default ]
159
160       ConfigDefault ignores 'where' completely (and also the DEFAULT entry)
161       and checks the 'options' database on the widget's behalf, and if an
162       entry is present matching dbName/dbClass
163
164           -attribute => value
165
166       is added to the list of options that new will eventually apply to the
167       widget. Likewise if there is not a match and default is defined this
168       default value will be added.
169
170       Alias entries in the hash are used to convert user-specified values for
171       the alias into values for the real attribute.
172
173   New()-time configure
174       Once control returns to new, the list of user-supplied options
175       augmented by those from ConfigDefault are applied to the widget using
176       the configure method below.
177
178       Widgets are most flexible and most Tk-like if they handle the majority
179       of their attributes this way.
180
181   Configuring composites
182       Once the above have occurred calls of the form:
183
184           $composite->configure( -attribute => value );
185
186       should behave like any other widget as far as end-user code is
187       concerned.  configure will be handled by Tk::Derived::configure as
188       follows:
189
190           $composite->ConfigSpecs;
191
192       is called (with no arguments) to return a reference to a hash
193       -attribute is looked up in this hash, if -attribute is not present in
194       the hash then 'DEFAULT' is looked for instead.  (Aliases are tried as
195       well and cause redirection to the aliased attribute).  The result
196       should be a reference to a list like:
197
198         [ where, dbName, dbClass, default ]
199
200       at this stage only where is of interest, it maps to a list of object
201       references (maybe only one) foreach one
202
203          $object->configure( -attribute => value );
204
205       is evaled.
206
207   Inquiring attributes of composites
208          $composite->cget( '-attribute' );
209
210       This is handled by  Tk::Derived::cget in a similar manner to configure.
211       At present if where is a list of more than one object it is ignored
212       completely and the "cached" value in
213
214          $composite->{Configure}{-attribute}.
215
216       is returned.
217

CAVEATS

219       The "-background" and "-foreground" option values are automatically
220       propagated down to all composite widget's children. This may be
221       sometimes not desirable, especially if some subwidgets should use own
222       color schemes, either by using explicit options or by option database
223       definitions. If this is the case, then just add
224
225           -foreground => 'SELF',
226           -background => 'SELF',
227
228       to "ConfigSpecs".
229
230       It is the author's intention to port as many of the "Tix" composite
231       widgets as make sense. The mechanism described above may have to evolve
232       in order to make this possible, although now aliases are handled I
233       think the above is sufficient.
234

NAME

SYNOPSIS

DESCRIPTION

CAVEATS

SEE ALSO