\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#186: Expose the Type and Modified-State of Widget Options}
\date{April 16, 2004}
\author{Peter MacDonald, Peter MacDonald}
\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 \#186}&\textbf{Expose the Type and Modified-State of Widget Options}\\\hline
Author&

Peter MacDonald \tipmail{pmacdona}{pdqi.com}
\par
Peter MacDonald \tipmail{peter}{pdqi.com}
\\
Created&Friday, \(\text{16}^{\text{th}}\) April 2004\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.4 $\\
Keywords&Tk\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP adds a 6th (and 7th element) to each option in the output of [\textit{path} \textbf{configure}] for Tk widgets, indicating the type and modified status of each option respectively.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The configure subcommand of Tk widgets provides a powerful method for introspection of widget state information. Unfortunately, two important pieces of information are currently unavailable. Namely, the type Tk is expecting for an option and the whether a user has explicitly assigned a value.

The type field is valuable in automating interfaces for editing the contents of widgets.

The modified field is useful in changing styles (such as in \textbf{tk\_setPalette}) where we update all widgets that are currently using default values.

\section{Specification}

The configure subcommand for Tk widgets, when invoked with no arguments, currently dumps out all options as a list with 5 elements per-option: optName, dbName, dbClass, defValue, optValue. This TIP proposes adding up to 2 additional values: \textbf{optType} and \textbf{optModified}.
\begin{itemize}
\item{}
A 6th element, \textbf{optType}, is a string representation of the type field of \textbf{Tk\_ConfigSpec} and \textbf{Tk\_OptionSpec}.
\item{}
For widgets using the new \textbf{Tk\_OptionSpec}, a 7th appended element indicates whether an option has been set by the user.
\end{itemize}

\section{Notes}

Perhaps \textbf{optModified} should be specified as an enumeration. For example:
\begin{itemize}
\item{}
1 = \textbf{USER\_MODIFIED}
\item{}
2 = \textbf{OPTION\_DATABASE}
\item{}
3 = \textbf{SYSTEM\_DEFAULT}
\item{}
4 = \textbf{TABLE\_DEFAULT}
\end{itemize}

In addition, as much of the Tk core is still using \textbf{Tk\_ConfigSpec}, would some form of compatibility interface make sense whereby a \textbf{Tk\_ConfigSpec} could be used to dynamically produce a \textbf{Tk\_OptionSpec}? (This last is out of the scope of this TIP.)

Probably also need a way to change options such that the \textbf{USER\_MODIFIED} flag does not get set. (eg. \textbf{tk\_setPalette})

\section{Changes}

Threre are a couple of small changes to \textit{tkConfig.c} and \textit{tkOldConfig.c}, plus a \#define of \textbf{TK\_OPTION\_VALUE\_SET} in \textit{tk.h}

\section{Overhead/Impact}

Scripts currently exploiting introspection and depending upon a list length of 5 may break.

\section{Reference Implementation}

There is a simple implementation of the above available as a patch against Tk 8.4.2[\url{http://pdqi.com/configure.diff.gz}]. It does not implement a enumerated flag for \textbf{optModified}, and the type string lookup is rather crude.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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