This procedure is used to tell the switched layer that the derived
class object (a car in the examples) is completely built.
At that time, the initial configuration of the switched object occurs,
using default option values (see procedure options)
eventually overridden by construction time values, passed at the time
of the new operator invocation.
This procedure must be called only once, usually around or at the end
of the derived class constructor.
(Note: Also check the complete data member later in this
chapter).

This procedure must return the configuration description for
all options that the switched object will accept.
It is a pure virtual member procedure and therefore its implementation
is mandatory in the derived class layer.
The procedure must return a list of lists.
Each list pertains to a single option and is composed of the switch
name, the default value for the option and an optional initial value.
For example:

In this case, 4 options are specified:
fuel, length, power and width.
The default and initial values for the fuel option are
identical and set to petrol.
For the other options, values are all empty.

For each option, there must be a corresponding
set-option procedure defined in the derived class
layer.
For example, since we defined a fuel option, there is a
set-fuel procedure in the car class.
The parameters always are the object identifier (since this is not a
static procedure, but rather a dynamically defined virtual one),
followed by the new value for the option.
A set-option procedure is only invoked if the new
value differs from the current one (a caching scheme for improving
performance), or if there is no initial value set in the
options procedure for that option.

In this procedure, if the initial value differs from the
default value or is omitted, then initial configuration is forced and
the corresponding set-option procedure is invoked by
the switched complete procedure located at the end of the
derived class constructor.
For example:

In this case, configuration is forced on the fuel and
power options, that is the corresponding
set-option procedures will be invoked when the
switched object is constructed (see set-option
procedures documentation below).

For the fuel option, since there is no initial value,
the set-fuel procedure is called with the default
value (petrol) as argument.
For the power option, since the initial value differs from
the default value, the set-power procedure is called
with the initial value as argument (50).

For the other options, since the initial values (last elements
of the option lists) are identical to their default values, the
corresponding set-option procedures will not be
invoked. It is the programmer's responsibility to insure that the
initial option values are correct.

Since the -width option was listed in the options
procedure, a set-width procedure implementation is provided, which
of course would proceed to set the width of the car (and would modify
the looks of a graphical representation, for example).

As you add a supported option in the list returned by
the options procedure, the corresponding
set-option procedure may be called as soon as the
switched object is complete, which occurs when the switched level
complete procedure is invoked.
For example:

In this case, a new car is created with no options, which
causes the car constructor to be called, which in turns calls the
switched level complete procedure after the car object layer
is completely initialized.
At this point, since there are no initial values in any option list in
the options procedure, the set-fuel procedure is called with
its default value of petrol as parameter, followed by the
set-length call with 4.5 value, set-power
with 350 value and finally with set-width with
1.8 as parameter.
This is a good way to test the set-option procedures
when debugging, and when done, just fill-in the initial option values.

The switched layer checks that an option is valid (that is,
listed in the options procedure) but obviously does not check
the validity of the value passed to the set-option
procedure, which should throw an error (for example by using the Tcl
error command) if the value is invalid.

The switched layer also keeps track of the options current
values, so that a set-option procedure is called
only when the corresponding option value passed as parameter is
different from the current value (see data members
description).

The data member is an options current value.
There is one for each option listed in the options procedure. It is a
read-only value which the switched layer checks against when an option
is changed.
It is rarely used at the layer derived from switched, except in the
few cases, such as in the following example:

In this case, the manufacturer's name is stored at the switched
layer level (this is why the set-manufacturer procedure has nothing to
do) and later retrieved in the printData procedure.

The data member (not to be confused with
the complete procedure) is a boolean.
Its initial value is false and it is set to true at
the very end of the switched complete procedure.
It becomes useful when some options should be set at construction time
only and not dynamically, as the following example shows:

This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category stooop of the
Tcllib Trackers.
Please also report any ideas for enhancements you may have for either
package and/or documentation.