\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#82: Add -offrelief Option to Checkbutton and Radiobutton}
\date{January 10, 2002}
\author{D. Richard Hipp}
\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 \#82}&\textbf{Add -offrelief Option to Checkbutton and Radiobutton}\\\hline
Author&

D. Richard Hipp \tipmail{drh}{hwaci.com}
\\
Created&Thursday, \(\text{10}^{\text{th}}\) January 2002\\
Type&Project\\
Tcl Version&\(8.4\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.4 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes adding option \textit{-offrelief} to the checkbutton and radiobutton widgets to specify the relief of the widget when \textit{-indicatoron} is off and the state of the button is off. This feature is needed to support the use of checkbutton and radiobutton widgets on toolbars.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

The checkbutton and radiobutton widgets both support the \textit{-overrelief} option which is suppose to provide the capability to change the relief of the widget on mouse-over. The \textit{-overrelief} option is not used by the underlying C code. The value of \textit{-overrelief} is used only by the script bindings to change the \textit{-relief} option in response to \textit{\tiplangle{}Enter\tiprangle{}} and \textit{\tiplangle{}Leave\tiprangle{}} events. But with the checkbutton and radiobutton widgets, the value of \textit{-relief} is ignored when \textit{-indicatoron} is turned off. Hence, \textit{-overrelief} has no effect when \textit{-indicatoron} is off.

An example of the effect we would like to achieve is the Bold/Italic/Underline and text justification toolbar buttons on word processors. The Bold/Italic/Underline toolbar buttons are most naturally implemented using Tk checkbuttons and the text justification toolbar buttons are most naturally implemented using Tk radiobuttons. The buttons are configured to be flat most of the time (\textit{-relief} flat) but raise up on mouseover (\textit{-overrelief} raised). Toolbar buttons do not show indicators (\textit{-indicatoron} off). This last configuration option is the crux of the problem since when \textit{-indicatoron} is off, the relief of the button is hard-coded to be raised when the button is on and sunken when the button is off. In the current implementation, there is no way to get the off-relief to be flat, and hence there is no way to achieve the customary look for these common toolbar buttons.

\section{Proposed Enhancement}

This TIP proposes to modify the checkbutton and radiobutton widgets to support a \textit{-offrelief} option. \textit{-offrelief} will take any of the usual relief values. The default value will be \textit{raised}. The \textit{-offrelief} option determines the relief of the widget when \textit{-indicatoron} option is off and the button itself is off.

The default bindings for checkbuttons and radiobuttons will also need to be changed so that they copy the value of \textit{-overrelief} into \textit{-offrelief} instead of into \textit{-relief} when the value of \textit{-indicatoron} is false.

When \textit{-indicatoron} is off and the button itself is on, the relief continues to be hard-coded to sunken. For symmetry, we might consider adding another \textit{-onrelief} option to cover this case. But it is difficult to imagine ever wanting to change the value of \textit{-onrelief} so it has been omitted from this TIP. If there as strong desire to have \textit{-onrelief}, it can be added later.

\section{Alternative Proposals}

A simpler solution would be to change the \textit{-indicatoron} option so that it causes the off-relief to come from the \textit{-relief} option instead of using a hard-coded \textit{raised} relief. That approach is conceptually simpler, but it breaks backwards compatibility and so must be rejected.

Another possibility is to modify \textit{-indicatoron} so that it takes a third value (other than \textit{on} or \textit{off}) where the third value works like \textit{off} but takes the off-relief from the \textit{-relief} option instead of always using \textit{raised}. But this second idea seems more contrived and makes it more difficult to define an alternative on-relief value with a later modification.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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