\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#19: Add a Text Changed Flag to Tk's Text Widget}
\date{January 03, 2001}
\author{Neil McKay}
\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 \#19}&\textbf{Add a Text Changed Flag to Tk's Text Widget}\\\hline
Author&

Neil McKay \tipmail{mckay}{eecs.umich.edu}
\\
Created&Wednesday, \(\text{3}^{\text{rd}}\) January 2001\\
Type&Project\\
Tcl Version&\(8.4\alpha2\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.6 $\\
Obsoleted By&26\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP adds a \textit{text changed} flag to the Tk text widget. The flag would initially be reset, but would be set whenever the contents of the text widget changes.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

When creating a text editor, it is often useful to know when the contents of the edit buffer have changed, e.g. in order to ask the user whether or not to save changes on exit. It is possible to create key bindings in Tk's text widget that will set a flag whenever the user changes the widget's contents; however, this is awkward, and it still requires that the programmer set the flag whenever text is changed programmatically. A better solution is to include a \textit{text changed} flag in the code for the text widget itself; this can be accomplished with a relatively small amount of code.

\section{Flag Behavior}

The \textit{text changed} flag should behave as follows:
\begin{itemize}
\item{}
It should be reset when the text widget is created
\item{}
It should be set whenever characters are inserted into or deleted from the widget
\item{}
It must be resettable programmatically via a Tcl command
\end{itemize}

\section{Reference Implementation}

At the Tcl level, one possible implementation is to add a \textit{changed} widget command to the text widget. One possible syntax for this command is:
\begingroup\small\begin{verbatim}
    .txt changed ?boolean?
\end{verbatim}
\endgroup

where .txt is a text widget. With no \textit{boolean} argument, the command returns the state of the text-changed flag; with an argument, it sets the state of the text-changed flag to the value of the argument.

\section{Example}

A typical sequence of commands in a text editor would be
\begin{enumerate}
\item{}
Create a text widget
\setcounter{enumi}{1}
\item{}
Read a file and put its contents into the text widget
\setcounter{enumi}{2}
\item{}
Mark the text as unchanged
\setcounter{enumi}{3}
\item{}
Edit the text
\setcounter{enumi}{4}
\item{}
Write the text out, if it has changed.
\end{enumerate}

This could be accomplished by the following Tcl code fragment:
\begingroup\small\begin{verbatim}
 grid [button .b -text Quit -command EndEdit]
 grid [text .t]

 proc EndEdit {} {
     if {[.t changed]} {
         set result [tk_messageBox -type yesno -message "Save changes?"]
         if {[string compare $result "yes"] == 0} {
             set fh [open $fileName "w"]
             puts -nonewline $fh [.t get 1.0 end-1c]
             close $fh
         }
     }
     exit
 }

 set fh [open $fileName "r"]
 .t insert end [read $fh]
 close $fh
 .t changed false
\end{verbatim}
\endgroup

\section{Copyright}

This document is in the public domain.

\section{Patch}

The \textit{changed} text widget command, as described above, may be added to Tk8.4a2 by applying the patch at \url{http://www.cs.man.ac.uk/fellowsd-bin/TIP/19.patch}

\section{Colophon}

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