Check-in [9a757d6209]

	Votes-Against:  KBK, JN, FV
	Votes-Present:  BG
	Vote-Comments:  code not yet ready, needs porting to macOS; alternate
	                might be to just co-distribute, just as TDBC is with Tcl
-----

# Abstract

## oo::class like widgets

The new widgets are implemented in C as oo::classes. The base class is **tko::widget**. These class create and handles the internal Tk\_Window and provide **cget** and **configure** methods. The **configure** method has additional functionality to add or delete options. The new widget functionality is documented in the [`tkoWidget.n.md`](https://core.tcl.tk/tk/doc/tip-510/doc/tkoWidget.n.md) file.

The new widgets **graph** and **path** are implemented as **oo::class**. This will make it easy to extent the functionality. As an example see the file `.../library/graph.tcl` in which the method **binding** of the **graph** widget is implemented.

## Enhanced **configure** functionality

**configure** *args*

> **configure**

> > If *args* is empty the method will return a sorted list of all configuration options.

> **configure** *-option*

> > If we have one element in *args* starting with a minus sign ("-") then the method return the configuration list including the current value of the given *-option*.

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

> > If we have an even number list in *args* and the first element starts with a minus sign ("-") then the method does configure all the given option-value pairs. If an error occurs the the corresponding element is not set and the method gives an error. Alrready successfull set options remain.

> **configure init**

> > This is an internal function used in constructing new widgets. It is used in the *unknown* method to initialize all options.

> **configure optionadd** *-synonym -option*

> > Add a *-synonym* for a given *-option*. The *-option* needs not to be defined at this time.

> **configure optionadd** *-synonym dbnam dbclass ?default? ?flags?*

> > Add a new option. If ?flags? is equal "1" then the option is readonly and can only be set in this call. Before adding a new option a *-option* method must created. The method will be called without any arguments. The method can access the new value using the *tko(-option)* array variable. If the method throws a n error the array variable will be reset to the old value.

> **configure 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.

> **configure optionvar**

> > The method return the global varname of the tko array variable holding all option values.

## New widgets

[Rbc][] aka "Refactored [BLT][] Components" have graph widgets and Tk commands which are missing in *Tk*.

[Tkpath][] is a 2D-canvas like widget modelled after [SVG][].

*Tk* has already **frame**, **labelframe** and **toplevel** widgets. These widgets have class like behaviour but are no real classes. It is p.e. not possible to add functionality to these widgets.

This TIP intends to add the following commands to Tk:

**rbc::graph**, **rbc::stripchart** and **rbc::barchart** as **graph**

> To get the original functionality a *-style* option will be added. This
option can only be set on creation time.

**rbc::vector** as **graph::vector**

> The vector is currently only used inside the graph widget. The namespace hidden version leaves room for a first class command with the same name.

**rbc::winop snap** as **tk snap**

> Only the snap functionality is needed here. The busy command already exists as "tk busy" :)

**tkp::canvas** as **path**

> The new path widget will contain the [SVG][] like items and an additional **window** item to include other windows. Support functions will be placed in the **::path** namespace.

**tko::frame** **tko::labelframe** and **tko::toplevel**

> These widgets have the same functionality like the normal tk widgets. They are implemented as oo::classes and it is possible to add/delete options.

# Rationale

## Rbc commands

*Tk* has already adopted some of [BLT][]/[Rbc][] commands.
Still missing are the above mentioned commands.

[Rbc][] is available on sourceforge and github, but the development is stalled.

[BLT][], the orignal source, is at sourceforge. The author G. Howlett makes sporadic changes. Then there are large times without activity. It is not possible to estimate when a new version will be ready.

Modernizing [Rbc][] and including it in *Tk* will give some great new widgets.
There is also less risk because [Rbc][] is already used in different projects.

## Tkpath

The original developer of [Tkpath][] passed away. There are some mirrors, but with no real development. More information could be found on <https://wiki.tcl-lang.org/page/tkpath>.

The intent of [Tkpath][] was to substitute the *Tk* canvas. This leads to problems with advanced features (matrix transformations). Therefore the new **path** widget will only contain [SVG][] like items. The only exception is the **window** item. This item is necessary to embed other widgets.

# Implementation

A patch implementing these changes is available in the fossil
repository in the [tip-510 branch](https://core.tcl.tk/tk/timeline?r=tip-510).

## Documentation

Documentation is in markdown syntax understood by fossil and can therefore accessed online. The files will be put in the directory `.../doc/`.

- [`tkoWidget.3.md`](https://core.tcl.tk/tk/doc/tip-510/doc/tkoWidget.3.md) tko::widget C-function documentation
- [`tkoWidget.n.md`](https://core.tcl.tk/tk/doc/tip-510/doc/tkoWidget.n.md) tko::widget Tcl command documentation
- [`graph.n.md`](https://core.tcl.tk/tk/doc/tip-510/doc/graph.n.md) graph widget documentation
- [`vector.n.md`](https://core.tcl.tk/tk/doc/tip-510/doc/vector.n.md) graph::vector command documentation
- [`path.n.md`](https://core.tcl.tk/tk/doc/tip-510/doc/path.n.md) path widget documentation

## C interface

Alle new functionality is in the following header files:

- [`tkoWidget.h`](https://core.tcl.tk/tk/doc/tip-510/generic/tko/tkoWidget.h) tko::widget function
- [`tkoGraph.h`](https://core.tcl.tk/tk/doc/tip-510/generic/tko/tkoGraph.h) graph functions
- [`tkoPath.h`](https://core.tcl.tk/tk/doc/tip-510/generic/tko/tkoPath.h) path functions

No functionality is currently exported. The new files are  added to the makefiles.

The initialization function **Tko\_Init** is added to the *tkInt.h* file and will be called in *tkWindow.c*.

## C sources

C-source code will be put in the directory `.../generic/tko/`

- [`tkoWidget.c`](https://core.tcl.tk/tk/doc/tip-510/generic/tko/tkoWidget.c) tko::widget implementation
- [`tkoFrame.c`](https://core.tcl.tk/tk/doc/tip-510/generic/tko/tkoFrame.c) tko::frame, tko::labelframe and tko::toplevel implementation
- `tkoPath*.c` tkpath widget implementation
- `tkoGraph*.c` graph widget implementation
- `tkoRbc*.c` graph related common [Rbc][] functions.
- `tkoVector*.c` graph vector commadn implementation

## Tcl source

Tcl-source code will be put in the directory `.../library/`

- [`graph.tcl`](https://core.tcl.tk/tk/doc/tip-510/library/graph.tcl) graph widget bindings
- [`path.tcl`](https://core.tcl.tk/tk/doc/tip-510/library/path.tcl) path widget helper function under **::path**

## Tests

Test files will be put in the directory `.../tests/tko/`

- [`tkoFrame.test`](https://core.tcl.tk/tk/doc/tip-510/tests/tko/tkoFrame.test) tko::frame, tko::labelframe and tko::toplevel widget tests. The tests are mostly identical to the corresponding tk widget tests.

- [`tkoGraph.test`](https://core.tcl.tk/tk/doc/tip-510/tests/tko/tkoGraph.test) graph widget tests
- [`tkoGraph_vector.test`](https://core.tcl.tk/tk/doc/tip-510/tests/tko/tkoGraph_vector.test) graph::vector command tests
- [`tkoPath.test`](https://core.tcl.tk/tk/doc/tip-510/tests/tko/tkoPath.test) path widget tests

# Examples

Add options at class level:

    oo::class create myWidget {
      {*}$::tko::unknown
      superclass ::tko::frame
      variable tko
      method -myoption {} {puts $tko(-myoption)}
      method -myreadonly {} {puts $tko(-myreadonly)}
      constructor {optionlist arglist} {
        next [concat {
          {-myoption myOption MyOption value}
          {-myreadonly myReadonly MyReadonly value 1}
        } $optionlist] $arglist
      }

    }

Deal with optons at object level. This is the raw part. May be we should add some sugar to it.

    myWidget .w
    oo::objdefine .w method -o1 {} {puts $tko(-o1)}
    oo::objdefine .w method -o2 {} {puts $tko(-o2)}
    .w configure optionadd -o1 o1 O1 v1 1
    .w configure optionadd -o2 o2 O2 v2
    ...
    .w optiondel -o1

Widget option values are saved in an option array. The option name is the field name in the array. Additionally is an field "**.**" containing the tk widget path name of the widget. The name of the option array variable can be retrieved using the following code:
    set myVar [.w configure optionvar]
    parray $myVar


# Discussion

See also discussion at the [wiki](http://wiki.tcl.tk/55360).

A first voting was rejected, mostly because of the missing Mac implementation. See:

<http://code.activestate.com/lists/tcl-core/20357/>  
<http://code.activestate.com/lists/tcl-core/20368/>  

and with some analysis from Donal:

<http://code.activestate.com/lists/tcl-core/20384/>  

# Open issues

- Mac implementation of **graph** widget. May be borrow code from **path**
- Remove or change old code in `generic/tko/tkoGraph*` and  `generic/tko/tkoRbc*` files <http://code.activestate.com/lists/tcl-core/20384/>
- Hardcoded usage of compiler and libraries in [`win/Makefile.in`](https://core.tcl.tk/tk/doc/tip-510/win/Makefile.in), [`win/makefile.vc`](https://core.tcl.tk/tk/doc/tip-510/win/makefile.vc) and [`unix/Makefile.in`](https://core.tcl.tk/tk/doc/tip-510/unix/Makefile.in) (search for "#RZ TODO").
- Add **path** files in Mac implementation. It works at least in [Androwish][].
- Which platforms should be used in **path**
  - SDL/AGG: platform independent, more work is needed using [`tkoPath_SDLAGG.cpp`](https://core.tcl.tk/tk/doc/tip-510/generic/tko/tkoPath_SDLAGGPath.cpp). See in [Androwish][]
  - GDI+ on Windows => working with [`tkoPath_WinGDIPlus.cpp`](https://core.tcl.tk/tk/doc/tip-510/generic/tko/tkoPath_WinGDIPlus.cpp)
  - Cairo on unix => working with [`tkoPath_UnixCairo.c`](https://core.tcl.tk/tk/doc/tip-510/generic/tko/tkoPath_UnixCairo.c)
  - For Mac see [`tkoPath_MacOSX.c`](https://core.tcl.tk/tk/doc/tip-510/generic/tko/tkoPath_MacOSX.c)
- Provide demos
- Add more **path** tests
- Is it necessary to translate the documentation into man format?
- It is currently not possible to use unique abbreviations of slass method names p.e. "graph .g; .g conf" A workaround would be to add all those method names. May be this can be solved in tcl::oo directly?

Any help especially with the Mac implementation would be great!

And could please look someone with `configure` foo at the Makefile's










# Alternatives

- Wait on new [BLT][].
- Develop widgets in extensions.

# Copyright