\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#180: Add a Megawidget Support Core Package}
\date{March 22, 2003}
\author{Damon Courtney}
\urlstyle{sf}
\setlength{\parskip}{1ex}
\setlength{\parindent}{0pt}
\def\tipversion$#1${\texttt{\$#1\$}}
\def\tiplangle#1{\ensuremath{<}}
\def\tiprangle#1{\ensuremath{>}}
\def\tipbar#1{\ensuremath{|}}
\def\tipmail#1#2{\(\langle\){\small\expandafter\url{#1@#2}}\(\rangle\)}
\ifx\pdfoutput\undefined
\newcommand{\tipimage}[2]{\typeout{Make sure you download #1.eps}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.eps}}{\includegraphics[width=0.8\textwidth]{#1.eps}}}
\newcommand{\tipxref}[1]{}
\newcommand{\tipxrefend}{}
\else
\newcommand{\tipimage}[2]{\typeout{Make sure you create #1.pdf}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.pdf}}{\includegraphics[width=0.8\textwidth]{#1.pdf}}}
\pdfcatalog{/PageMode /UseOutlines}
\newcommand{\tipxref}[1]{\pdfannotlink attr {/C [0.5 0.5 1.0] /Border [0 0 1]} goto name {#1}}
\newcommand{\tipxrefend}{\pdfendlink}
\fi
\newenvironment{tipabstract}{\begin{abstract}}{\end{abstract}}
\begin{document}\maketitle
\begin{center}\begin{tabularx}{\linewidth}{|r@{: }X|}\hline
\textbf{TIP \#180}&\textbf{Add a Megawidget Support Core Package}\\\hline
Author&

Damon Courtney \tipmail{damon}{unreality.com}
\\
Created&Saturday, \(\text{22}^{\text{nd}}\) March 2003\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.5 $\\
Keywords&Tk\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes the addition of a ``megawidget'' package to Tk as a core package which contains a set of functions useful for building megawidgets with standard script-level behaviour in Tk.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

It's obvious (to me at least) from the (growing) number of pure-Tcl megawidget packages that it would be very helpful for Tk to provide some mechanism to help all these various packages do things in some standard way.

For example, there is a base set of options and commands that are supported by all Tk core widgets that should also be supported in any megawidget. Now, most of the packages do their job at supporting these, but I think a lot of it could be done very easily through a common method that would ensure that any megawidget created in this manor has not only a standard set of options and commands, but those commands will also produce standard error messages and the like.

Though I am not opposed to this TIP being added to Tk's core, I propose it as a core package only because the only time its functions are really needed is when working with a megawidget library. These functions don't do much to help the average Tk developer and are mostly meant for the developer's developer.

This TIP does not seek to tell megawidget extension writers how they should write their widgets. Eveyone has their own ideas of how that should be done. This package merely provides some helper functions to try and speed up the most common widget functions.

\section{Specification}

The commands for this package are all written in C for speed reasons. After testing different megawidget packages, I find that most of them are very slow at the most basic widget functions like \textbf{cget} and \textbf{configure}. That was why I set out to write all of the standard functions in C and provide the hooks for various packages to use them instead of all the homegrown solutions that have been used.

The following commands would be part of the package:

\textbf{::megawidget::class} \textit{widgetClass}

\begin{quote}
Define a new megawidget class.
\end{quote}

\textbf{::megawidget::commands} \textit{widgetClass} ?\textit{command ...}?

\begin{quote}
Define a list of subcommands available to widgets of \textit{widgetClass}.
\end{quote}

\textbf{::megawidget::options} \textit{widgetClass} ?\textit{optionList ...}?

\begin{quote}
Define the options available to widgets of \textit{widgetClass}. An \textit{optionList} is a list describing the option:
\end{quote}

\begin{quote}
\textit{type option dbClass dbName defValue}
\end{quote}

\begin{quote}
The \textit{type} value can be \textbf{boolean}, \textbf{int}, \textbf{double}, \textbf{string}, \textbf{enum}, \textbf{color}, \textbf{font}, \textbf{bitmap}, \textbf{border}, \textbf{relief}, \textbf{cursor}, \textbf{justify}, \textbf{anchor}, \textbf{synonym}, \textbf{pixels}, or \textbf{window}. The other values should be familiar to users of Tk's standard \textbf{configure} subcommand.
\end{quote}

\textbf{::megawidget::create} \textit{widgetName widgetClass commandName}

\begin{quote}
Create a new megawidget of class \textit{widgetClass} from \textit{widgetName}. \textit{widgetName} must already exist as a widget, and its widget command will be renamed to \textit{commandName} and replaced by a new command that will handle the defined subcommands for the widget class.
\end{quote}

\textbf{::megawidget::cget} \textit{pathName option}

\begin{quote}
Get the value of a megawidget option for \textit{pathName}. This function is also called as a result of [\textit{pathName} \textbf{cget}].
\end{quote}

\textbf{::megawidget::configure} \textit{pathName} ?\textit{option}? ?\textit{value option value ...}?

\begin{quote}
Configure or query option values for the megawidget \textit{pathName}. This function is also called as a result of [\textit{pathName} \textbf{configure}].
\end{quote}

The options of a widget are stored and retrieved in dictionaries. The \textbf{configure} and \textbf{cget} commands are handled by the widget command after a widget is created, and all other commands are passed to the author to handle.

Some options (like \textbf{-cursor}, \textbf{-background}, \textbf{-borderwidth}, \textbf{-bg}, \textbf{-bd}) should probably be created for all megawidgets, but that has yet to be decided and is open for discussion.

\section{Author's Note}

I have completed work on this package with all the functions written in C and with great care to keep them as fast and efficient as possible.

Porting the BWidget ButtonBox to SNIT and doing some test is what got me to this point. I was simply trying to create a widget and do a \textbf{cget}. The results were pretty disappointing considering the very basic \textbf{cget} command.
\begingroup\small\begin{verbatim}
 Native Tk widget: 2 microseconds
 BWidget widget:   60 microseconds
 SNIT widget:      260 microseconds
\end{verbatim}
\endgroup

With \textbf{::megawidget::cget}, I get around 4 microseconds, which is pretty close to native Tk widgets.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\end{document}
