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