Tk Source Code

# tkoWidget(3) -- oo class like widgets

*   [NAME](#NAME)
*   [SYNOPSIS](#SYNOPSIS)
*   [ARGUMENTS](#ARGUMENTS)
*   [DESCRIPTION](#DESCRIPTION)
*   [SEE ALSO](#SEE-ALSO)
*   [KEYWORDS](#KEYWORDS)
*   [COPYRIGHT](#COPYRIGHT)

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

Tko\_WidgetClassDefine,
Tko\_WidgetCreate,
Tko\_WidgetDestroy,
Tko\_WidgetClientData,
Tko\_WidgetOptionGet,
Tko\_WidgetOptionSet,

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

**#include "tkoWidget.h"**

int
**Tko\_WidgetClassDefine**(*interp,classname,methods,options*)
int
**Tko\_WidgetCreate**(*clientdata,interp,object,createmode,arglist*)
void
**Tko\_WidgetDestroy**(*context*)
ClientData
**Tko\_WidgetClientData**(*context*)
Tcl\_Obj \*
**Tko\_WidgetOptionGet**(*widget,option*)
int
**Tko\_WidgetOptionSet**(*widget,option,value*)

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

| Tcl\_Interp **\*interp** | Used interpreter.
| Tcl\_Obj **\*classname** |Oo class name of widget.
| const Tcl\_MethodType **\*methods** | This array defines class methods to create. For creation methods see [Tcl\_NewMethod] manpage. If the method name of the first array entry is not NULL it will be used as **constructor**, if the second method name is not NULL it used as **destructor**. Then follow public methods until an entry with an method name equal NULL comes. Then follow private methods until an entry with an method name equal NULL comes.
| const Tko\_WidgetOptionDefine **\*options** | This array contain option definitions.
| Tcl\_Object **object** | This is the current object reference.
| Tko_WidgetCreateMode **createmode** | When =1 then create a toplevel otherwise a frame window.
| Tcl\_Obj **arglist** | Argument list of constructor call.
| ClientData **cientdata** | Pointer to widget structure. First part in this struct is Tko\_Widget. It
| Tcl\_ObjectContext **context** | Context of method calls.
| Tcl\_Obj **\*option** | The name of the used option.
| Tcl\_Obj **\*value** | New value of the given option.

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

The **Tko\_WidgetClassDefine** function create a new tko widget class of *classname*. The function create the class add common methods (cget, configure, \_tko\_configure) and then add given methods and options.

The **Tko\_WidgetCreate** function create a new window. The *clientdata* should be *ckalloc*ed in the widget constructor. The function add the given *clientdata* to the object metadata. The function should be called in a C widget constructor.

The **Tko\_WidgetDestroy** function clears all internal widget data. The function also arrange the *ckfree* of the *clientdata*.

The **Tko\_WidgetClientData** should be used from inside widget methods to get the widget structure data given in the **Tko\_WidgetCreate** function.

The **Tko\_WidgetOptionGet** function returns the current value of the given option.

The **Tko\_WidgetOptionSet** function set the given *option* to the new given *value*.

### Enum: `Tko_WidgetOptionType`

Suported enum type in the **Tko\_WidgetOptionDefine** definition. As comment is the type of the address provided in the **Tko\_WidgetOptionDefine** definition.

    typedef enum Tko\_WidgetOptionType {
        TKO_SET_CLASS = 1,     /* (Tcl_Obj **)address */
        TKO_SET_VISUAL, /* (Tcl_Obj **)address */
        TKO_SET_COLORMAP,       /* (Tcl_Obj **)address */
        TKO_SET_USE,        /* (Tcl_Obj **)address */
        TKO_SET_CONTAINER,      /* (int *)address */
        TKO_SET_TCLOBJ, /* (Tcl_Obj **)address */
        TKO_SET_XCOLOR, /* (Xcolor **)address */
        TKO_SET_3DBORDER,       /* (Tk_3DBorder *)address */
        TKO_SET_PIXEL,  /* (int *)address */
        TKO_SET_PIXELNONEGATIV, /* (int *)address */
        TKO_SET_PIXELPOSITIV,   /* (int *)address */
        TKO_SET_DOUBLE, /* (double *)address */
        TKO_SET_BOOLEAN,        /* (int *)address */
        TKO_SET_CURSOR, /* (Tk_Cursor *)address */
        TKO_SET_INT,    /* (int *)address */
        TKO_SET_RELIEF, /* (int *)address */
        TKO_SET_ANCHOR, /* (int *)address */
        TKO_SET_WINDOW, /* (Tk_Window *)address */
        TKO_SET_FONT,   /* (Tk_Font *)address */
        TKO_SET_STRING, /* (char **)address */
        TKO_SET_SCROLLREGION,   /* (int *[4])address */
        TKO_SET_JUSTIFY /* (Tk_Justify *)address */
    } Tko\_WidgetOptionType;

### Enum: `Tko_WidgetCreateMode`

Supported values in **Tko\_WdigetCreate()** function call.

    typedef enum Tko_WidgetCreateMode {
      TKO_CREATE_WIDGET, /* Create new widget */
      TKO_CREATE_TOPLEVEL, /* Create new toplevel widget */
      TKO_CREATE_CLASS, /* See "tko initclass" */
      TKO_CREATE_WRAP /* See "tko initwrap" */
    } Tko_WidgetCreateMode;

### Struct: `Tko_WidgetOptionDefine`

Widget definition data used in class.
An option set method "-option" is created in the following order:
  - "option"=NULL indicate the end of a list of option definitions.
  - If "method" is given it will be used as option set method.
  - If "type" is greater 0 a common option set method will be used.
    In this case "offset" are used as offset in the widget structure.

    typedef struct Tko_WidgetOptionDefine {
        const char *option;    /* Name of option. Starts with "-" minus sign */
        const char *dbname;    /* Option DB name or synonym option if dbclass is NULL */
        const char *dbclass;   /* Option DB class name or NULL for synonym options. */
        const char *defvalue;  /* Default value. */
        int flags;             /* bit array of TKO_OPTION_* values to configure option behaviour */
        Tcl_MethodCallProc *method;    /* If not NULL it is the function name of the -option method */
        Tko_WidgetOptionType type;  /* if greater 0 then option type used in common option set method */
        int offset;            /* offset in meta data struct */
    } Tko_WidgetOptionDefine;
    #define TKO_OPTION_READONLY 0x1 /* option is only setable at creation time */

### Struct: `Tko_Widget`

Widget structure data used in objects.
These structure will be filled in the **Tko\_WidgetCreate** call and cleared in
the **Tko\_WidgetDestroy** call. Widget methods should check the value of *tkWin* on NULL before using it.

    typedef struct Tko_Widget {
        Tk_Window tkWin;       /* Window that embodies the widget. NULL means
                                * that the window has been destroyed but the
                                * data structures haven't yet been cleaned
                                * up.*/
        Display *display;      /* Display containing widget. Used, among
                                * other things, so that resources can be
                                * freed even after tkwin has gone away. */
        Tcl_Interp *interp;    /* Interpreter associated with widget. */
        Tcl_Command widgetCmd; /* Token for command. */
        Tcl_Object object;     /* our own object */
        Tcl_Obj *myCmd;        /* Objects "my" command. Needed to call internal methods. */
        Tcl_Obj *optionsArray; /* Name of option array variable */
        Tcl_HashTable *optionsTable; /* Hash table containing all used options */
    } Tko_Widget;


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

    static Tko_WidgetOptionDefine myOptions[] = {
        /*
         * Readonly option, only setable on creation time.
         * Use of internal standard option setting function.
         */
        {"-class","class","Class","TkoFrame",TKO_OPTION_READONLY,
            NULL,NULL,TKO_SET_CLASS,NULL,0},
        /*
         * Option value in structure have NULL value when option is empty.
         * Use of internal standard option setting function.
         */
        {"-background","background","Background",DEF_FRAME_BG_COLOR,TKO_OPTION_NULL,
            NULL,NULL,TKO_SET_3DBORDER,&frameMeta,offsetof(tkoFrame, border)},
        /*
         * Use own provided oo method to set option value.
         */
        {"-backgroundimage","backgroundImage","BackgroundImage",DEF_FRAME_BG_IMAGE,0,
            NULL,FrameMethod_backgroundimage,0,NULL,0},
        /*
         * Synonym option definition.
         */
        {"-bg","-background",NULL,NULL,0,NULL,NULL,0,NULL,0},
        /*
         * Indicate end of options in array.
         */
        {NULL,NULL,NULL,NULL,0,NULL,NULL,0,NULL,0}
    };

For detailed examples see also the implementation of **tko::toplevel**, **tko::frame** and **tko::labelframe** widgets in file generic/tko/tkoFrame.c.

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

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

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

oo widget method option

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

&copy; 2019- René Zaumseil <[email protected]>

BSD style license.

[options]: options.htm
[frame]: frame.htm
[labelframe]: labelframe.htm
[toplevel]: toplevel.htm
[oo::class]: class.htm
[graph]: graph.htm
[path]: path.htm
[Tkpath]: <https://sourceforge.net/projects/tclbitprint/>
[Rbc]: <https://sourceforge.net/projects/rbctoolkit/>

# tko(n) -- oo class like widgets

*   [SYNOPSIS](#SYNOPSIS)
*   [TKO STANDARD OPTIONS](#TKO-STANDARD-OPTIONS)
  [-class, class, Class](#-class)
  [-screen, screen, Screen](#-screen)
*   [DESCRIPTION](#DESCRIPTION)
*   [PUBLIC METHODS](#PUBLIC-METHODS)
*   [PRIVATE METHODS](#PRIVATE-METHODS)
*   [OPTIONS](#OPTIONS)
*   [EXAMPLES](#EXAMPLES)
*   [SEE ALSO](#SEE-ALSO)
*   [KEYWORDS](#KEYWORDS)
*   [COPYRIGHT](#COPYRIGHT)

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

### Tko widgets

**::tko::toplevel** *pathName ?option value? ..*

**::tko::frame** *pathName ?option value? ..*

**::tko::labelframe** *pathName ?option value? ..*

### Class functions

**::tko initclass**

**::tko initfrom** *tkoclass*

**::tko initwrap** *widget readonlyoptionlist methodlist*

**::tko eventoption**

**::tko optiondef** *classname ?-option definitionlist? .. ?body?*

**::tko optiondel** *classname ?-option? ..*

**::tko optionget** *classname ?-option? ..*

**::tko optionhide** *classname ?-option? ..*

**::tko optionshow** *classname ?-option? ..*

### Widget methods

**my \_tko optionadd** *-option definitionlist ?body?*

**my \_tko optiondel** *-option* ..

**my \_tko optionhide** *-option* ..

**my \_tko optionshow** *-option* ..

<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

### Option definitionlist

In the *definitionlist* description below an entry with name *flags* can contain a combination of the following letters:

  - "r" the option is readonly and can only be set on creation
  - "h" The option is hidden from use in **cget** and **configure** methods.

The *definitionlist* can have one of the following forms:

  - *{-synonym flags}*

> Description of an synonym option. When *-option* is set then instead the provided *-synonym* option will be set.

  - *{dbname dbclass default flags}*

> Description of an option.
If *dbname* or *dbclass* is not empty then the values will be used to search for an default option value in the option database.
The search will need a **Tk\_Window** and therefore this definition can only be used in an widget class.
If both value are empty then the option definition can be used in an normal class create with **tko initclass**.
*default* is the default value if no value can be found in the option database.

### Function **::tko**

**::tko initclass**

> The function will create public **constructor**, **destructor**, **cget** and **configure** methods and private **_tko** and **_tko_configure** methods in the current class.

> The function can be used to add **cget** and **configure** functionality to an normal oo class.
No additional functionality is added.

> The function should be called only once inside the "oo::class create" script.
When called the list of used options will be cleared.

**::tko initfrom** *tkoclass*

> This function will provide the necessary initialization of an oo class as tko widget.
The argument *tkoclass* should be an **tko** widget class.
The class *tkoclass* will be the superclass of the current widget and all options of *tkoclass* will be added to our new class.

> If you create your own **constructor**, **destructor**, **cget** or **configure** methods you need to call **next** inside these function to call the function of the *tkoclass* superclass.

> The function should be called only once inside the "oo::class create" script.
When called the list of used options will be cleared.

**::tko initwrap** *widget readonlyoptionlist methodlist*

> This function will wrap an existing normal tk widget as an tko widget class.
The argumen *widget* is the name of the normal tk widget.
The argument *readonlyoptionlist* is a list of all readonly options of the given *widget*.
The argument *methodlist* is a list of methods to link to the wrapped *widget*.

> The function will create public **constructor**, **destructor**, **cget** and **configure** methods and private **_tko** and **_tko_configure** methods in the current class.

> The function should be called only once inside the "oo::class create" script.
When called the list of used options will be cleared.

**::tko eventoption**

> This option will send an <<TkoEventChanged>> virtual event to all widgets.
If a option value was set using the option database then the value of this option will updated with the current value of the option database.
The option database can so be used as a style source.

**::tko optiondef** *classname ?-option definitionlist? .. ?body?*

> The function will add or replace all given *-option definitionlist* pairs to the given *classname*. If an additional ?body? argument is given it will be used to create the *-option* method of the last given *-option* in *classname*

**::tko optiondel** *::classname ?-option? ..*

> The function will remove the given options from the defined class options of the given *::classname*. If no option is given then all existing options will be removed.

**::tko optionget** *::classname ?-option? ..*

> This function will return a list of *-option definitionlist* pairs ready for use in the **::tko optiondef** command.
The list consist of the specified options or all options if there are no options given.
THe option will be read from the fully qualified ?::classname? definitions.

**::tko optionhide** *::classname ?-option ..*

> Hide the given options from the use in **cget** and **configure** methods. If no options are given then return the list of all hidden options.

**::tko optionshow** *::classname ?-option ..*

> Unhide the given options from the use in **cget** and **configure** methods. If no options are given then return the list of all useable options.

<a name="tko-toplevel"></a>
### Widget **::tko::toplevel**

These class contain the functionality of the [toplevel][] widget command.

<a name="tko-frame"></a>
### Widget **::tko::frame**

These class contain the functionality of the [frame][] widget command.

<a name="tko-labelframe"></a>
### Widget **::tko::labelframe**

These class contain the functionality of the [labelframe][] widget command.

<a name="PUBLIC-METHODS"></a>
## PUBLIC METHODS

Widget methods can be dynamically added and removed at class or object level.

**NOTE** Do not change *tkoClass*'s behaviour. Instead create your own class and modify it to your need! Or change created widget objects behaviour.

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

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

<a name="method-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 vlaue* pairs to set options.

<a name="PRIVATE-METHODS"></a>
## PRIVATE METHODS

<a name="method-_tko"></a>
**my \_tko optionadd** *-option definitionlist ?body?*

> Add a new option in the current object. The meaning of the *definitionlist* argument is the same as in the **::tko optionset** command.
The function will only add new options.
It is not possible to change object options.

**my \_tko optiondel** *-option* ..

> Delete the given option and unset the entry in the tko array variable. The created *-option* method's are not deleted. This is the task of the caller.

**my \_tko optionhide** *-option* ..

> If no *-option* is given return a list of all not configure'able options. Otherwise hide all of the given options.

**my \_tko optionshow** *-option* ..

> If no *-option* is given return a list of all configure'able options. Otherwise make all of the given options configure'able.

<a name="method-tko-configure"></a>
**my \_tko\_configure**

> This is an virtual method of the *tkoClass* widgets. 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="OPTIONS"></a>
## OPTIONS

Widget option values are saved in an option array **tko**. The option name is the field name in the array. Additionally is an field "**.**" containing the tk widget path name of the widget.

Widget options can be dynamically added and removed at class or object level.
It is possible to hide and unhide options.

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

    #
    # Configurable object
    #
    oo::class create A {
      ::tko initclass
    }
    A create a1
    a1 configure ==>

    # Add class option
    ::tko optiondef A -o1 {o1 O1 v1 {}} {set tko(-o1) x}
    A create a2
    a2 configure
    ==> {-o1 o1 O1 v1 v1}

    # Add object option
    oo::define A method mycmd {args} {my {*}$args}
    a2 mycmd _tko optionadd -o2 {o2 O2 v2 {}} {variable tko; set tko(-o2) x}
    a2 configure
    ==> {-o1 o1 O1 v1 v1} {-o2 o2 O2 v2 x}

    #
    # Wrap an existing widget
    #
    oo::class create B {
      ::tko initwrap frame {-class -container -colormap -visual} {}
    }
    B .b
    lindex [.b configure] 0
    ==> {-background background Background SystemButtonFace SystemButtonFace}

    #
    # Create a new widget class.
    #
    oo::class create C {
      ::tko initfrom ::tko::frame
      constructor {args} {next {*}$args}
      destructor {next}
      method mycmd {args} {my {*}$args}
    }

    # Hide all inherited frame options
    ::tko optionhide C {*}[::tko optionhide C]
    ::tko optionshow C
    ==> -class -visual -colormap -container -borderwidth ...
    C .c
    .c configure
    ==>

    # Add a new option
    oo::define C method -o1 {} {puts $tko(-o1)}
    ::tko optiondef C -o1 {o1 O1 v1 {}}
    ::tko optionhide C
    ==> -o1

    # Add another option
    ::tko optiondef C -o2 {o2 O2 v2 {}} {puts $tko(-o2)}
    ::tko optionhide C
    ==> -o1 -o2

    # Add options at object level:
    C .c1
    .c1 mycmd _tko optionadd -o3 {o3 O3 v3 {}} {my variable tko; puts $tko(-o3)}
    .c1 configure
    ==> {-o1 o1 O1 v1 v1} {-o2 o2 O2 v2 v2} {-o3 o3 O3 v3 v3}

    # Show all frame options again
    .c1 mycmd _tko optionshow {*}[.c1 mycmd _tko optionshow]
    llength [.c1 configure]
    ==> 24

    # Intercept options
    oo::define C method -width {} {
        puts "[my cget -width]->$tko(-width)->[set tko(-width) 100]"
    }
    .c1 configure -width 1
    ==> 0->1->100

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

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

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

oo widget method option

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

&copy; 2019- René Zaumseil <[email protected]>

BSD style license.

[options]: options.htm
[frame]: frame.htm
[labelframe]: labelframe.htm
[toplevel]: toplevel.htm
[oo::class]: class.htm

/*
 * Themed widget set init function:
 */

MODULE_SCOPE int	Ttk_Init(Tcl_Interp *interp);

/*
 * Tko widget set init function:
 */

MODULE_SCOPE int	Tko_Init(Tcl_Interp *interp);

/*
 * Internal functions shared among Tk modules but not exported to the outside
 * world:
 */

MODULE_SCOPE int	Tk_BellObjCmd(ClientData clientData,
			    Tcl_Interp *interp, int objc,

     * Initialized the themed widget set
     */

    code = Ttk_Init(interp);
    if (code != TCL_OK) {
	goto done;
    }

    /*
     * Initialized the tko widget set
     */

    code = Tko_Init(interp);
    if (code != TCL_OK) {
	goto done;
    }

    /*
     * Invoke platform-specific initialization. Unlock mutex before entering
     * TkpInit, as that may run through the Tk_Init routine again for the
     * console window interpreter.
     */