Tk::ConfigSpecs(3pm)

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

NAME

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

CAVEATS

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

NAME

SYNOPSIS

DESCRIPTION

CAVEATS

SEE ALSO