1switched(n)       Simple Tcl Only Object Oriented Programming      switched(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       switched - switch/option management.
9

SYNOPSIS

11       package require Tcl  8.3
12
13       package require switched  ?2.2.1?
14
15       <switched> complete this
16
17       <switched> options this
18
19       <switched> set-option this value
20
21______________________________________________________________________________
22

DESCRIPTION

24       The  switched class serves as base class for user classes with switch /
25       option configuration procedures. It provides  facilities  for  managing
26       options through a simple interface.
27
28       For example:
29
30
31              set vehicle [new car -length 4.5 -width 2 -power 100 -fuel diesel]
32              puts "my car was running on [switched::cget $vehicle -fuel]"
33              switched::configure $vehicle -power 40 -fuel electricity
34              puts "but is now running on clean [switched::cget $vehicle -fuel]"
35
36
37       Of course, as you might have guessed, the car class is derived from the
38       switched class. Let us see how it works:
39
40
41              class car {
42                  proc car {this args} switched {$args} {
43                      # car specific initialization code here
44                      switched::complete $this
45                  }
46                  ...
47              }
48
49
50       The switched class constructor takes the optional configuration  option
51       /  value pairs as parameters.  The switched class layer then completely
52       manages the switched options: it checks their  validity,  stores  their
53       values  and  provides a clean interface to the user layer configuration
54       setting procedures.
55
56       The switched class members available to the programmer are:
57
58       <switched> complete this
59              This procedure is used to  tell  the  switched  layer  that  the
60              derived  class  object  (a  car  in  the examples) is completely
61              built.  At that time, the initial configuration of the  switched
62              object  occurs,  using  default  option  values  (see  procedure
63              options) eventually  overridden  by  construction  time  values,
64              passed  at the time of the new operator invocation.  This proce‐
65              dure must be called only once, usually around or at the  end  of
66              the  derived  class constructor.  (Note: Also check the complete
67              data member later in this chapter).
68
69       <switched> options this
70              This procedure must return the configuration description for all
71              options that the switched object will accept.  It is a pure vir‐
72              tual member procedure and therefore its implementation is manda‐
73              tory  in  the  derived class layer.  The procedure must return a
74              list of lists.  Each list pertains to a  single  option  and  is
75              composed  of  the  switch name, the default value for the option
76              and an optional initial value.  For example:
77
78
79
80              class car {
81                  ...
82                  proc options {this} {
83                      return [list [list -fuel petrol petrol] [list -length {} {}] [list -power {} {}] [list -width {} {}] ]
84                  }
85                  proc set-fuel {this value} {
86                      ...
87                  }
88                  ...
89              }
90
91
92       In this case, 4 options are specified: fuel, length, power  and  width.
93       The  default  and  initial values for the fuel option are identical and
94       set to petrol.  For the other options, values are all empty.
95
96       For each option, there must be  a  corresponding  set-option  procedure
97       defined  in  the  derived class layer.  For example, since we defined a
98       fuel option, there is a set-fuel  procedure  in  the  car  class.   The
99       parameters always are the object identifier (since this is not a static
100       procedure, but rather a dynamically defined virtual one),  followed  by
101       the  new  value for the option.  A set-option procedure is only invoked
102       if the new value differs from the current one  (a  caching  scheme  for
103       improving  performance),  or  if  there  is no initial value set in the
104       options procedure for that option.
105
106       In this procedure, if the initial value differs from the default  value
107       or is omitted, then initial configuration is forced and the correspond‐
108       ing set-option procedure is invoked by the switched complete  procedure
109       located at the end of the derived class constructor.  For example:
110
111
112              class car {
113                  ...
114                  proc options {this} {
115                      return [list [list -fuel petrol] [list -length {} {}] [list -power 100 50] [list -width {} {}] ]
116                  }
117                  ...
118              }
119
120
121              In  this  case,  configuration  is  forced on the fuel and power
122              options, that is the corresponding set-option procedures will be
123              invoked  when the switched object is constructed (see set-option
124              procedures documentation below).
125
126              For the fuel option, since there is no initial value,  the  set-
127              fuel  procedure  is  called  with  the default value (petrol) as
128              argument.  For the power option, since the initial value differs
129              from  the  default value, the set-power procedure is called with
130              the initial value as argument (50).
131
132              For the other options, since the initial values  (last  elements
133              of  the option lists) are identical to their default values, the
134              corresponding set-option procedures will not be invoked.  It  is
135              the  programmer's  responsibility  to  insure  that  the initial
136              option values are correct.
137
138       <switched> set-option this value
139              These procedures may be viewed  as  dynamic  virtual  functions.
140              There  must  be  one  implementation  per  supported  option, as
141              returned by the options procedure.  For example:
142
143
144              class car {
145                  ...
146                  proc options {this} {
147                      return [list ...
148                          [list -width {} {}] ]
149                  }
150                  ...
151                  proc set-width {this value} {
152                      ...
153                  }
154                  ...
155              }
156
157
158              Since the -width option was listed in the options  procedure,  a
159              set-width  procedure implementation is provided, which of course
160              would proceed to set the width of the car (and would modify  the
161              looks of a graphical representation, for example).
162
163              As  you  add  a  supported  option  in  the list returned by the
164              options procedure, the corresponding set-option procedure may be
165              called  as soon as the switched object is complete, which occurs
166              when the switched level  complete  procedure  is  invoked.   For
167              example:
168
169
170
171              class car {
172                  proc car {this args} switched {args} {
173                      ...
174                      switched::complete $this
175                 }
176                  ...
177                  proc options {this} {
178                      return [list [list -fuel petrol] [list -length 4.5] [list -power 350] [list -width 1.8] ]
179                  }
180                  proc set-fuel {this value} {
181                      ...
182                  }
183                  proc set-length {this value} {
184                      ...
185                  }
186                  proc set-power {this value} {
187                      ...
188                  }
189                  proc set-width {this value} {
190                      ...
191                  }
192              }
193
194              new car
195
196
197       In  this  case,  a new car is created with no options, which causes the
198       car constructor to be called, which in turns calls the  switched  level
199       complete  procedure  after  the car object layer is completely initial‐
200       ized.  At this point, since there are no initial values in  any  option
201       list  in  the  options procedure, the set-fuel procedure is called with
202       its default value of petrol as parameter, followed  by  the  set-length
203       call  with  4.5  value,  set-power with 350 value and finally with set-
204       width with 1.8 as parameter.  This is a good way to test the set-option
205       procedures  when  debugging,  and  when  done, just fill-in the initial
206       option values.
207
208       The switched layer checks that an option is valid (that is,  listed  in
209       the options procedure) but obviously does not check the validity of the
210       value passed to the set-option procedure, which should throw  an  error
211       (for example by using the Tcl error command) if the value is invalid.
212
213       The  switched  layer also keeps track of the options current values, so
214       that a set-option procedure  is  called  only  when  the  corresponding
215       option  value  passed  as parameter is different from the current value
216       (see  data members description).
217
218
219       The  data member is an options current value.
220              There is one for each option listed in the options procedure. It
221              is  a  read-only  value  which the switched layer checks against
222              when an option is changed.  It  is  rarely  used  at  the  layer
223              derived  from  switched, except in the few cases, such as in the
224              following example:
225
226
227
228              ...
229              proc car::options {this} {
230                  return {
231                      ...
232                      {-manufacturer {} {}}
233                      ...
234                  }
235              }
236
237              proc car::set-manufacturer {this value} {}
238
239              proc car::printData {this} {
240                  puts "manufacturer: $switched::($this,-manufacturer)"
241                  ...
242              }
243
244
245       In this case, the manufacturer's name is stored at the  switched  layer
246       level  (this  is  why the set-manufacturer procedure has nothing to do)
247       and later retrieved in the printData procedure.
248
249
250       The  data member (not to be confused with
251              the complete procedure) is a  boolean.   Its  initial  value  is
252              false and it is set to true at the very end of the switched com‐
253              plete procedure.  It becomes useful when some options should  be
254              set  at  construction time only and not dynamically, as the fol‐
255              lowing example shows:
256
257
258
259              proc car::set-width {this value} {
260                  if {$switched::($this,complete)} {
261                      error {option -width cannot be set dynamically}
262                  }
263                  ...
264              }
265
266

BUGS, IDEAS, FEEDBACK

268       This document, and the package it describes, will  undoubtedly  contain
269       bugs  and other problems.  Please report such in the category stooop of
270       the  Tcllib  Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please
271       also  report any ideas for enhancements you may have for either package
272       and/or documentation.
273
274       When proposing code changes, please provide unified diffs, i.e the out‐
275       put of diff -u.
276
277       Note  further  that  attachments  are  strongly  preferred over inlined
278       patches. Attachments can be made by going  to  the  Edit  form  of  the
279       ticket  immediately  after  its  creation, and then using the left-most
280       button in the secondary navigation bar.
281

KEYWORDS

283       C++, class, object, object oriented
284

CATEGORY

286       Programming tools
287
288
289
290tcllib                               2.2.1                         switched(n)
Impressum