1option(n)                         [incr Tcl]                         option(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       itcl::option  - define options for extendedclass, widget or widgetadap‐
9       tor
10
11       Parts of this description are "borrowed" from Tcl extension [snit],  as
12       the functionality is mostly identical.
13

WARNING!

15       This  is  new  functionality  in  [incr  Tcl]  where  the API can still
16       change!!
17

SYNOPSIS

19       option optionSpec ?defaultValue?
20       option optionSpec ?options?
21______________________________________________________________________________
22
23

DESCRIPTION

25       The option command is  used  inside  an  [incr Tcl]  extendedclass/wid‐
26       get/widgetadaptor definition to define options.
27
28       In  the  first  form  defines an option for instances of this type, and
29       optionally gives it an initial value. The initial value defaults to the
30       empty string if no defaultValue is specified.
31
32       An  option  defined  in  this  way  is said to be locally defined.  The
33       optionSpec is a list defining the option's  name,  resource  name,  and
34       class name, e.g.:
35
36                  option {-font font Font} {Courier 12}
37
38       The  option  name  must  begin  with a hyphen, and must not contain any
39       upper case letters. The resource name and class name are  optional;  if
40       not specified, the resource name defaults to the option name, minus the
41       hyphen, and the class name defaults to the resource name with the first
42       letter  capitalized. Thus, the following statement is equivalent to the
43       previous example:
44
45                  option -font {Courier 12}
46
47       See The Tk Option Database for  more  information  about  resource  and
48       class names.
49
50       Options  are  normally  set  and  retrieved using the standard instance
51       methods configure and cget; within instance code (method bodies, etc.),
52       option values are available through the options array:
53
54                  set myfont $itcl_options(-font)
55
56       In  the  second  form  you  can  define option handlers (e.g., -config‐
57       uremethod), then it should probably use configure and  cget  to  access
58       its options to avoid subtle errors.
59
60       The option statement may include the following options:
61
62       -default defvalue
63              Defines  the  option's default value; the option's default value
64              will be "" otherwise.
65
66       -readonly
67              The option is handled read-only -- it can only be set using con‐
68              figure at creation time, i.e., in the type's constructor.
69
70       -cgetmethod methodName
71              Every  locally-defined  option  may  define a -cgetmethod; it is
72              called when the option's  value  is  retrieved  using  the  cget
73              method.  Whatever  the  method's body returns will be the return
74              value of the call to cget.
75
76              The named method must take one argument, the  option  name.  For
77              example,  this code is equivalent to (though slower than) Itcl's
78              default handling of cget:
79
80                             option -font -cgetmethod GetOption
81                             method GetOption {option} {
82                                 return $itcl_options($option)
83                             }
84
85              Note that it's possible for any number of  options  to  share  a
86              -cgetmethod.
87
88       -cgetmethodvar varName
89              That is very similar to -cgetmethod, the only difference is, one
90              can define a variable, where to find the cgetmethod during  run‐
91              time.
92
93       -configuremethod methodName
94              Every  locally-defined  option may define a -configuremethod; it
95              is called when the option's value is set using the configure  or
96              configurelist  methods.  It is the named method's responsibility
97              to save the option's value; in other words, the value  will  not
98              be  saved to the itcl_options() array unless the method saves it
99              there.
100
101              The named method must take two arguments, the  option  name  and
102              its  new value.  For example, this code is equivalent to (though
103              slower than) Itcl's default handling of configure:
104
105                             option -font -configuremethod SetOption
106                             method SetOption {option value} {
107                                 set itcl_options($option) $value
108                             }
109
110              Note that it's possible for any number of  options  to  share  a
111              single -configuremethod.
112
113       -configuremethodvar varName
114              That  is  very  similar to -configuremethod, the only difference
115              is, one can define a variable, where to find the configuremethod
116              during runtime.
117
118       -validatemethod methodName
119              Every locally-defined option may define a -validatemethod; it is
120              called when the option's value is set  using  the  configure  or
121              configurelist  methods,  just  before  the  -configuremethod (if
122              any). It is the named method's responsibility  to  validate  the
123              option's  new  value,  and  to  throw  an  error if the value is
124              invalid.
125
126              The named method must take two arguments, the  option  name  and
127              its  new  value.   For  example, this code verifies that -flag's
128              value is a valid Boolean value:
129
130                             option -font -validatemethod CheckBoolean
131                             method CheckBoolean {option value} {
132                                 if {![string is boolean -strict $value]} {
133                                     error "option $option must have a boolean value."
134                                 }
135                             }
136
137              Note that it's possible for any number of  options  to  share  a
138              single -validatemethod.
139
140       -validatemethodvar varName
141              That is very similar to -validatemethod, the only difference is,
142              one can define a variable, where to find the validatemethod dur‐
143              ing runtime.
144
145

KEYWORDS

147       option, widget, widgetadaptor, extendedclass
148
149
150
151itcl                                  4.0                            option(n)
Impressum