tko(n) -- oo class like widgets

SYNOPSIS

Tko widget commands

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

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

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

Tko widget class initialization

::tko::init

::tko::init tkoclass

::tko::init widgetcommand optionlist methodlist

Tko options

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

::tko::option classname delete ?-option? ..

::tko::option classname get ?-option? ..

::tko::option classname hide ?-option? ..

::tko::option classname show ?-option? ..

::tko::optionchanged ?widget?

Tko commands

::tko::snap window photo ?x? ?y? ?width? ?height? ?imagewidth? ?imageheight?

Widget methods

my _tko_configure

my _tko_option -option definitionlist ?body?

my _tko_option delete -option ..

my _tko_option hide -option ..

my _tko_option show -option ..

my _tko_wrap pathname args

TKO STANDARD OPTIONS

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.

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.

DESCRIPTION

Function ::tko::init

::tko::init

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::init 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::init widgetcommand optionlist methodlist

This function will wrap an existing normal tk widget as an tko widget class. The argument widgetcommand is the command to create the internal, wrapped widget. The argument optionlist is a list of options of the given widgetcommand. The given options will be added to the current widget class. An entry of * will add all options. The argument methodlist is a list of methods to link to the wrapped widgetcommand.

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.

Function ::tko::option

The definitionlist, used below, can have one of the following two forms:

  • {-synonym flag}

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

  • {dbname dbclass default flag}

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 values are empty then the option definition can be used in an normal class created with tko::init. default is the default value if no value can be found in the option database.

In both types the flag entry is a single letter. If the letter is lower case then the option is hidden. This means the option can be used inside the defining class but can not be used in cget and configure call from outside. The following letters are supported:

  • o,O Normal option.
  • r,R Readonly option. The option can only be set at creation time.
  • v,V Variable option. It is a normal option like above. The option can not be deleted. This is used in C coded options.
  • c,C Constant option. It is a readonly option like above. The Option can not be deleted. This is used in C coded options.
  • w,W Wrapped option. The option is used to provide access to opiotns of wrapped widgets.

::tko::option classname -option definitionlist -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::option ::classname delete ?-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::option ::classname get ?-option? ..

This function will return a list of -option definitionlist pairs ready for use in the ::tko::option definition 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::option ::classname hide ?-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::option ::classname show ?-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.

Function ::tko::optionchanged

::tko::optionchanged widget

This option will send an <> virtual event to all widgets under the given widget. If no widget parameter is given the value of "widget" is "."

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.

Function ::tko::snap

::tko::snap window photo ?x? ?y? ?width? ?height? ?imagewidth? ?imageheight?

Get content from window and put it into given photo image. The size of the original window content can be limited with the parameters x, y ?width? ?height?. To scale the resulting image use the parameters ?imagewidth? ?imageheight?

Widget ::tko::toplevel

These class contain the functionality of the toplevel widget command.

Widget ::tko::frame

These class contain the functionality of the frame widget command.

Widget ::tko::labelframe

These class contain the functionality of the labelframe widget command.

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.

cget -option

Return the current value of the given option.

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.

PRIVATE METHODS

my _tko_configure -option definitionlist ?body?

This function will be called after changing options with the configure method. Derived classes can implement it to do own configurations.

my _tko_option -option definitionlist ?body?

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

my _tko_option delete -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_option hide -option ..

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

my _tko_option show -option ..

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

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.

my _tko_wrap pathname args

This is a only internally used function. It will create the original widget in the constructor of wrapped widgets. Do not use it directly!

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.

EXAMPLES

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

# Add class option
::tko::option 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_option add -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 init ::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 init ::tko::frame
  constructor {args} {next {*}$args}
  destructor {next}
  method mycmd {args} {my {*}$args}
}

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

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

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

# Add options at object level:
C .c1
.c1 mycmd _tko_option add -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_option show {*}[.c1 mycmd _tko_option show]
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

SEE ALSO

frame, labelframe, toplevel, oo::class

KEYWORDS

oo widget method option

COPYRIGHT

© 2019- RenĂ© Zaumseil r.zaumseil@freenet.de

BSD style license.