manpagez: man pages & more
man itcloption(n)
Home | html | info | man
option(n)                         [incr Tcl]                         option(n)



______________________________________________________________________________


NAME

       itcl::option  - define options for extendedclass, widget or widgetadap-
       tor

       Parts of this description are "borrowed" from Tcl extension [snit],  as
       the functionality is mostly identical.


WARNING!

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


SYNOPSIS

       option optionSpec ?defaultValue?
       option optionSpec ?options?
______________________________________________________________________________



DESCRIPTION

       The option command is  used  inside  an  [incr Tcl]  extendedclass/wid-
       get/widgetadaptor definition to define options.

       In  the  first  form  defines an option for instances of this type, and
       optionally gives it an initial value. The initial value defaults to the
       empty string if no defaultValue is specified.

       An  option  defined  in  this  way  is said to be locally defined.  The
       optionSpec is a list defining the option's  name,  resource  name,  and
       class name, e.g.:

                  option {-font font Font} {Courier 12}

       The  option  name  must  begin  with a hyphen, and must not contain any
       upper case letters. The resource name and class name are  optional;  if
       not specified, the resource name defaults to the option name, minus the
       hyphen, and the class name defaults to the resource name with the first
       letter  capitalized. Thus, the following statement is equivalent to the
       previous example:

                  option -font {Courier 12}

       See The Tk Option Database for  more  information  about  resource  and
       class names.

       Options  are  normally  set  and  retrieved using the standard instance
       methods configure and cget; within instance code (method bodies, etc.),
       option values are available through the options array:

                  set myfont $itcl_options(-font)

       In  the  second  form  you  can  define option handlers (e.g., -config-
       uremethod), then it should probably use configure and  cget  to  access
       its options to avoid subtle errors.

       The option statement may include the following options:

       -default defvalue
              Defines  the  option's default value; the option's default value
              will be "" otherwise.

       -readonly
              The option is handled read-only -- it can only be set using con-
              figure at creation time, i.e., in the type's constructor.

       -cgetmethod methodName
              Every  locally-defined  option  may  define a -cgetmethod; it is
              called when the option's  value  is  retrieved  using  the  cget
              method.  Whatever  the  method's body returns will be the return
              value of the call to cget.

              The named method must take one argument, the  option  name.  For
              example,  this code is equivalent to (though slower than) Itcl's
              default handling of cget:

                             option -font -cgetmethod GetOption
                             method GetOption {option} {
                                 return $itcl_options($option)
                             }

              Note that it's possible for any number of  options  to  share  a
              -cgetmethod.

       -cgetmethodvar varName
              That is very similar to -cgetmethod, the only difference is, one
              can define a variable, where to find the cgetmethod during  run-
              time.

       -configuremethod methodName
              Every  locally-defined  option may define a -configuremethod; it
              is called when the option's value is set using the configure  or
              configurelist  methods.  It is the named method's responsibility
              to save the option's value; in other words, the value  will  not
              be  saved to the itcl_options() array unless the method saves it
              there.

              The named method must take two arguments, the  option  name  and
              its  new value.  For example, this code is equivalent to (though
              slower than) Itcl's default handling of configure:

                             option -font -configuremethod SetOption
                             method SetOption {option value} {
                                 set itcl_options($option) $value
                             }

              Note that it's possible for any number of  options  to  share  a
              single -configuremethod.

       -configuremethodvar varName
              That  is  very  similar to -configuremethod, the only difference
              is, one can define a variable, where to find the configuremethod
              during runtime.

       -validatemethod methodName
              Every locally-defined option may define a -validatemethod; it is
              called when the option's value is set  using  the  configure  or
              configurelist  methods,  just  before  the  -configuremethod (if
              any). It is the named method's responsibility  to  validate  the
              option's  new  value,  and  to  throw  an  error if the value is
              invalid.

              The named method must take two arguments, the  option  name  and
              its  new  value.   For  example, this code verifies that -flag's
              value is a valid Boolean value:

                             option -font -validatemethod CheckBoolean
                             method CheckBoolean {option value} {
                                 if {![string is boolean -strict $value]} {
                                     error "option $option must have a boolean value."
                                 }
                             }

              Note that it's possible for any number of  options  to  share  a
              single -validatemethod.

       -validatemethodvar varName
              That is very similar to -validatemethod, the only difference is,
              one can define a variable, where to find the validatemethod dur-
              ing runtime.



KEYWORDS

       option, widget, widgetadaptor, extendedclass



itcl                                  4.0                            option(n)

tcl 8.6.9 - Generated Fri Nov 16 19:11:26 CST 2018
© manpagez.com 2000-2025
Individual documents may contain additional copyright information.