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