# tko(n) -- oo class like widgets

*   [SYNOPSIS](#SYNOPSIS)
*   [TKO STANDARD OPTIONS](#TKO-STANDARD-OPTIONS)  
  [-class, class, Class](#-class)  
  [-screen, screen, Screen](#-screen)  
*   [DESCRIPTION](#DESCRIPTION)  
  [Tko class and option initialization](#Tko-initialization)  
  [Tko public methods](#Tko-public-methods)  
  [Tko private methods](#Tko-private-methods)  
*   [EXAMPLES](#EXAMPLES)  
*   [SEE ALSO](#SEE-ALSO)  
*   [KEYWORDS](#KEYWORDS)  
*   [COPYRIGHT](#COPYRIGHT)  

<a name="SYNOPSIS"></a>
## SYNOPSIS

[**tko::widget**](#tko::widget)*tkowidget widget ?usepatterns? ?ignorelist?*

<a name="Tko-initialization"></a>
### Tko class and option initialization

[**tko_createclass**](#tko_createclass)

[**tko_createwidget**](#tko_createwidget)

[**tko_createsuperclass**](#tko_createsuperclass) *tkoclass*

[**tko_createsuperwidget**](#tko_createsuperwidget) *tkowidget*

[**tko_option**](#tko_option)
 
[**tko_option**](#tko_option) *-option*
 
[**tko_option**](#tko_option) *-option -synonym*

[**tko_option**](#tko_option) *-option dbname dbclass default body ?startbody?*

<a name="Tko-public-methods"></a>
### Tko public methods

[**configure**](#configure) *?-option? ?value?..*

[**cget**](#cget) *-option*

<a name="Tko-private-methods"></a>
### Tko private methods

[**my _tko_constructor**](#_tko_constructor) *arglist ?widget? ?widgetargs?* 
 
[**my _tko_destructor**](#_tko_destructor)

[**my _tko_init**](#_tko_init) *?classname?*

[**my _tko_configure**](#_tko_configure)

<a name="TKO-STANDARD-OPTIONS"></a>
## TKO STANDARD OPTIONS

<a name="-class"></a>
Command-Line Name: **-class**  
Database Name: **class**  
Database Class: **Class**

> Define class for use in getting values from option database. Can only be set on widget creation time. The option should be the first option in the option definition list because it is needed to get other option values from the option database. Only the **-screen** option can precede it.

<a name="-screen"></a>
Command-Line Name: **-screen**  
Database Name: **screen**  
Database Class: **Screen**

> Affect creation of underlying widget structure. If given the created widget will be a toplevel widget. The option should be the very first option of an widget to be recognised.

<a name="DESCRIPTION"></a>
## DESCRIPTION

<a name="tko::widget"></a>
**tko::widget** *tkowidget widget ?usepatterns? ?ignorelist?*

> This function will create an new *tkoclass* from the given *widget* with all options matching one of the *usepatterns* and not in *ignorelist. If no *usepatterns* is given then all options will be used. Additionally all methods of the original *widget* are available in the new *tkowidget*.

### Tko class and option initialization

The following commands should be called inside an oo::class context.

To initialize Tko classes one of the **tko_createclass**, **tko__createwidget*, tko_createsuperclass** or **tko_createsuperwidget** functions should be called in the class creation script.

Tko classes provide the **cget**, **configure** functionality known from Tk widgets. Widget objects can also read and write option values with the **tko** array variable, p.e. "set tko(-width) $tko(-height)".

Internally two class related variables (Tko and Tko\_) are used to save option related informations. Access and adding of new options are provided with the **tko_option** function.

<a name="tko_createclass"></a>
**tko_createclass**

> This is a convinience function to initialize the current class as tko class. The function will add the following variables and methods in the current class context.

- Object related **tko** array variables for saving of option values.
- Internal, class related **Tko** variables for saving of option definitions.
- Public **cget** and **configure** methods
- Private **_tko_constructor**, **_tko_init** and **_tko_configure** methods

<a name="tko_createwidget"></a>
**tko_createwidget**

> This is a convinience function to initialize the current class as tko widget. The not necessary class methods **create, createWithNamespace, destroy, new** will be removed and the **unknown** method will be changed to match normal Tk widget creation expectations. The function will add the following variables and methods in the current class context.

- Object related **tko** array variables for saving of option values.
- Internal, class related **Tko** variables for saving of option definitions.
- Public **cget** and **configure** methods
- Private **_tko_constructor**, **_tko_init** and **_tko_configure** methods

<a name="tko_createsuperclass"></a>
**tko_createsuperclass** *tkoclass*

> This is a convinience function to use tko features in the current class. It will add the given *tkoclass* as superclass. The function will add the following variables.

- Object related **tko** array variables for saving of option values.
- Internal, class related **Tko** variables for saving of option definitions.

<a name="tko_createsuperwidget"></a>
**tko_createsuperwidget** *tkowidget*

> This is a convinience function to use tko features in the current class. It will add the given *tkowidget* as superclass. The not necessary class methods **create, createWithNamespace, destroy, new** will be removed and the **unknown** method will be changed to match normal Tk widget creation expectations. The function will add the following variables.

- Object related **tko** array variables for saving of option values.
- Internal, class related **Tko** variables for saving of option definitions.

<a name="tko_optionadd"></a>
**tko_optionadd** *widget ?usepatterns? ?ignorelist?*

> This function will create new options in the current class. The options will be retrieved from the given *widget* with all options matching one of the *usepatterns* and not in *ignorelist. If no *usepatterns* is given then all options will be used.

<a name="tko_option"></a>
**tko_option**

> The function will return all option definitions of the current class.
 
**tko_option** *-option*
 
> The function will return the definition of the given option in the current class.

**tko_option** *-option -synonym*

> The function will create a new synonym option.

**tko_option** *-option dbname dbclass default body ?startbody?*

> The function will create a new Tk like option. If *dbname* and *dbclass* are empty the option database is ignored. This can be used to add options to tcl only classes. The parameters *-option dbname dbclass default* have the same meaning as in normal Tk options definitions.

> Option values are in the *tko* array variable as *tko(-option)* values. The values will be set in the innermost *_tko_constructor* call.

> The parameter *body* and *startbody* contain the body of the *-option* method. These method will be called for each setting of the *tko(-option)* variable.

> If both parameters are given then the *-option* method body will be set to *startbody*. The method will be called at the end of the *_tko_constructor* call and then the *-option* method body will be set to *body*. With this construct it is possible to create readonly options. To do this the *body* should contain "error readonly". Attention, in this use case the *body* will be use in the *oo::objdefine* context and needs a "variable tko" command to access the *tko* class variable!

> If only *body* is given then the *-option* method body will be set to this value. The variable *tko(-option)* will be set in the *_tko_constructor* call and the *-option* method will be called in the *_tko_init* call of the defining class of this option.

### Tko public methods

<a name="cget"></a>
**cget** *-option*

> Return the current value of the given *option*.

<a name="configure"></a>
**configure**

> The method will return a sorted list of all configuration options.

**configure** *-option*

> Return value of given option.

**configure** *-option value* ..

> Use given *-option value* pairs to set options.

### Tko private methods

<a name="_tko_constructor"></a>
**my _tko_constructor** *arglist ?widget? ?widgetargs?* 
 
> This method should be called at the start of the constructor if the class was created with **tko__createclass** or **tko_createwidget**. *arglist* is the list of *option value* pairs to configure the current class.

> If the current class was created with *::tko_createwidget* then the parameter *widget* should contain a widgetcommand. With these widgetcommand a widget will be created and used as replacement for the current object name. The widget name is accessible as value of **tko(.)**. The internal widget is still directly accessible with as value of **tko(..)**.

> The *widgetargs* parameters will be used to configure the given *widget*. It is possible to use values of tko options here.

<a name="_tko_destructor"></a>
**my _tko_destructor**

> Remove internal tko related data. Should be called in the class destructor method of classes defined with *::tko_createclass* or *::tko_createwidget*.

<a name="_tko_init"></a>
**my _tko_init** *?classname?*

> This function should be called in each constructor. The function will call the *-option* functions of options defined in the current class. The parameter *classname* is only necessary when the function is called from C-coded widgets.

<a name="_tko_configure"></a>
**my _tko_configure**

> This is an virtual method of the *tko* classes. This method will be called at the end of each **configure** *-option value ..* call. It can be implemented in each class to make necessary changes. If it is implemented it should also call **next** to notify underlying classes.

<a name="EXAMPLES"></a>
## EXAMPLES

    #
    # Class with options
    #
    oo::class create A {
        tko_createclass
        tko_option -class class Class myClass {error readonly} {}
        tko_option -o1 o1 O1 value1 {}
        constructor args {
            my _tko_constructor $args
            my _tko_init
        }
        destructor {my _tko_destructor}
    }
    ==> ::A
    A create a1
    ==> ::a1
    a1 configure
    ==> {-class class Class myClass myClass} {-o1 o1 O1 value1 value1}
    # Add class option
    oo::define A tko_option -o2 o2 O2 v2 {set tko(-o2) x}
    ==> -class {class Class myClass {error readonly}} -o1 {o1 O1 value1} -o2 {o2 O2 v2}
    A create a2
    ==> ::A2
    a2 configure 
    ==> {-class class Class myClass myClass} {-o1 o1 O1 value1 value1} {-o2 o2 O2 v2 x}
    #
    # Inheritance with options
    #
    oo::class create B {::tko_createsuperclass A}
    ==> ::B
    oo::define B {
        constructor args {
            next {*}$args
            my _tko_init
        }
    }
    B create b1
    ==> ::b1
    b1 configure
    ==> {-class class Class myClass myClass} {-o1 o1 O1 value1 value1} {-o2 o2 O2 v2 x}

    #
    # Create a new widget class.
    #
    oo::class create C {
        tko_createwidget
        tko_option -class class Class myWidget {error readonly} {}
        constructor args {
            my _tko_constructor $args ::frame {-class $tko(-class)}
            my _tko_init
        }
        destructor {my _tko_destructor}
    }
    ==> ::C
    C .c
    ==> .c
    .c configure
    ==> {-class class Class myWidget myWidget} 

    #
    # Extend existing tko widget class.
    #
    oo::class create D {
        tko_createsuperwidget ::C
        tko_option -o1 o1 O1 value1 {}
        constructor args {
            next {*}$args
            my _tko_init
        }
    }
    D .d
    .d configure
    ==> {-class class Class myWidget myWidget} {-o1 o1 O1 value1 value1}

    #
    # Wrap an existing widget
    #
    tko::widget E ::frame
    ==> ::E
    E .e
    ==> .e
    lindex [.e configure] 0
    ==> {-background background Background SystemButtonFace SystemButtonFace}

<a name="SEE-ALSO"></a>
## SEE ALSO

[tko][], [frame][], [labelframe][], [toplevel][], [oo::class][]

<a name="KEYWORDS"></a>
## KEYWORDS

oo widget method option

<a name="COPYRIGHT"></a>
## COPYRIGHT

&copy; 2019- René Zaumseil <r.zaumseil@freenet.de>

BSD style license.

[tko]: <https://chiselapp.com/user/rene/repository/tko/home>
[options]: <https://www.tcl.tk/man/tcl/TkCmd/options.htm>
[tko::frame]: <https://www.tcl.tk/man/tcl/TkCmd/frame.htm>
[tko::labelframe]: <https://www.tcl.tk/man/tcl/TkCmd/labelframe.htm>
[tko::toplevel]: <https://www.tcl.tk/man/tcl/TkCmd/options.htm>
[oo::class]: <https://www.tcl.tk/man/tcl/TclCmd/class.htm>
[tko::snap]: <https://chiselapp.com/user/rene/repository/tko/doc/trunk/doc/tko_snap.n.md>
[tko::path]: <https://chiselapp.com/user/rene/repository/tko/doc/trunk/doc/tko_path.n.md>
[tko::graph]: <https://chiselapp.com/user/rene/repository/tko/doc/trunk/doc/tko_graph.n.md>
