\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#271: Windows-Style Open and Save File Dialog on Unix}
\date{July 11, 2006}
\author{Matthew Middleton, susanta kumar mishra}
\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 \#271}&\textbf{Windows-Style Open and Save File Dialog on Unix}\\\hline
Author&

Matthew Middleton \tipmail{matthew.middleton}{ansys.com}
\par
susanta kumar mishra \tipmail{hi.skmishra}{gmail.com}
\\
Created&Tuesday, \(\text{11}^{\text{th}}\) July 2006\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.5 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP describes updates to the Unix file dialogs to make them more like the dialogs found on the Windows platform. This increases the usability of the dialog for general ``power'' users.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

It is nice to have a windows-type file dialog for Unix applications that wish to have a Windows appearance. This makes the experience much smoother for end-users that are experienced with the Windows file dialogs, which is an extremely common case these days.

It has convienent attributes of being able to reorder file lists by name, type, size, and date. It also has the typical cut, copy, paste, rename, delete, new directory and properties selections.

Box selecting is also possible with the multiple option. As much functionality as possible was included to match the windows dialog. Some things were left out, such as the panel at the left of a typical windows dialog that contains buttons that allow quick change to such things as ``My Documents, and ''My Computer".

\section{Reference Implementation}

The source code has been included as script files. All of this was done at the Tcl script level, and can be found in Patch 1520742 (currently written against Tcl/Tk 8.4.12). [\url{http://sf.net/tracker/?func=detail&aid=1520742&group_id=12997&atid=312997}] Listing of modified/new files:
\begingroup\small\begin{verbatim}
tkfbox.tcl
choosedir.tcl
tkfprops.tcl
Tkfprops.html
ResizeButs.tcl
ResizeButs.html
\end{verbatim}
\endgroup

Two new megawidgets have been developed for these changes. They are \textbf{ResizeButs} which is a button-alike specialized for acting as the heading of a column or row of data, and \textit{'tk\_fileProperties} which is a popup window for viewing and editing file metadata.

\section{Specification}

The \textbf{tk\_getOpenFile} and \textbf{tk\_getSaveFile} have been greatly improved to function much like a Windows file dialog (circa Windows 2000), when the default dialogs are overridden. This is most useful on Unix systems where the application is wanted to have a Windows-like appearance, but it will also function on Windows. I have not been able to test on Macintosh.

This also affects \textbf{tk\_chooseDirectory} when the default dialogs are overridden, as that is also implemented in \textit{tkfbox.tcl}.

The dialogs will work without the BWidget package, but it will have more functionality and look more like a windows dialog if BWidgets are available. The only thing it really needs from BWidgets is the \textbf{ComboBox} widget. If this were included in regular Tk, then BWidgets would not be needed. It also uses the balloon messages of the ``Button'' widget from BWidgets.

This new file dialog widget requires two of the new widgets included --- \textbf{ResizeButs} and \textbf{tk\_fileProperties}, which are autoloaded from \textit{ResizeButs.tcl} and \textit{tkfprops.tcl} respectively. The two tcl files that define these widgets are included, along with documentation on each one.

The file \textit{choosedir.tcl} is also included. It is needed to work with the modified \textit{tkfbox.tcl}.

\subsection{Functionality Outline}

Added functionality of the file dialog:
\begin{enumerate}
\item{}
Back directory button
\setcounter{enumi}{1}
\item{}
Create directory button
\setcounter{enumi}{2}
\item{}
Details button
\setcounter{enumi}{3}
\item{}
Delete button
\setcounter{enumi}{4}
\item{}
You can type the directory path at the top (requires BWidgets). Selecting ``desktop'' expands what's available on the desktop if used on Windows.

Right mouse clicking on a file gives these options:
\begin{enumerate}
\item{}
Cut
\setcounter{enumii}{1}
\item{}
Copy
\setcounter{enumii}{2}
\item{}
Delete
\setcounter{enumii}{3}
\item{}
Rename
\setcounter{enumii}{4}
\item{}
Properties (uses tk\_fileProperties widget)
\end{enumerate}

Right mouse clicking in open white space gives these options:
\begin{enumerate}
\item{}
View
\item{}
List
\setcounter{enumii}{1}
\item{}
Details
\setcounter{enumii}{1}
\item{}
Arrange Icons
\begin{enumerate}
\item{}
By Name
\setcounter{enumiii}{1}
\item{}
By Size
\setcounter{enumiii}{2}
\item{}
By Type
\setcounter{enumiii}{3}
\item{}
By Date
\end{enumerate}
\setcounter{enumii}{2}
\item{}
Refresh
\setcounter{enumii}{3}
\item{}
Paste (ungreys if Cut or Copy were previously selected on files)
\setcounter{enumii}{4}
\item{}
New Folder
\setcounter{enumii}{5}
\item{}
Properties (uses tk\_fileProperties widget)
\end{enumerate}
\setcounter{enumi}{5}
\item{}
Recent selected files can be shown by pressing the down arrow in the entry field of the selected file name (requires BWidgets). Recent file names are saved to a file named .tk\_recent\_selections in the users home directory.
\setcounter{enumi}{6}
\item{}
Box selecting of files can be done with the ``multiple 1'' option. Left mouse click and hold and drag a box over files.
\setcounter{enumi}{7}
\item{}
The busy was improved to actually block mouse clicks instead of just showing an hourglass widget.
\setcounter{enumi}{8}
\item{}
Popup button descriptions. (requires BWidgets)
\setcounter{enumi}{9}
\item{}
Icons shade as well as text when selected.
\end{enumerate}

\subsection{Details View}

The Details button grids 4 columns (name, file type, size, and modified date). (This uses ResizeButs widget.)

Moving the mouse over the border between two buttons of the top column headings and left mouse clicking while dragging will allow the user to change the size of the columns.

Pressing one of the heading buttons changes the order of the data between increasing and decreasing and displays a triangle in the button to indicate the order.

\subsection{Additional Arguments to the tk\_getOpenFile and tk\_getSaveFile Commands}

The \textit{dir\_leaf} arguments allow a folder to be selected as a file to select it as a project. Providing a \textbf{-dir\_leaf\_check} procedure defines the file dialog as a special type that only lists folders, but the folder that passes the \textbf{-dir\_leaf\_check} procedure can be selected as a file.
\begin{enumerate}
\item{}
\textbf{-dir\_leaf\_check} \textit{commandName} --- This is the name of a procedure which checks if the directory qualifies as the kind that can be selected as a project file. It returns a non-zero number if it qualifies, otherwise it returns zero. The directory name to check will be appended as an argument to the procedure.
\setcounter{enumi}{1}
\item{}
\textbf{-dir\_leaf\_image} \textit{imageName} --- an image to use for the folder types that will be treated as files. It should be an image created with \textbf{image create photo}.
\setcounter{enumi}{2}
\item{}
\textbf{-dir\_leaf\_label} \textit{string} --- text that appears at the left of the entry for the selected file when the dialog is defined as a project folder selection type (when the \textbf{-dir\_leaf\_check} procedure is defined). Not localized by Tk.
\setcounter{enumi}{3}
\item{}
\textbf{-extra\_widgets\_bottom} \textit{commandName} --- This is the name of a procedure which packs or grids additional widgets at the bottom of the dialog. The window name of a frame widget at the bottom of the dialog is appended as an argument, and any further widgets that this procedure creates to be gridded should be a child window of this frame. If this procedure returns anything, it will be treated as a number to configrue the width of the Ok and Cancel buttons, since the additional widgets could possibly stretch these buttons to any length.
\setcounter{enumi}{4}
\item{}
\textbf{-extra\_widgets\_side} \textit{commandName} --- This is the name of a procedure which does the packing or gridding for additional widgets at the right side of the dialog. The frame window name at the right side of the dialog will be appended as an argument.
\setcounter{enumi}{5}
\item{}
\textbf{-pick\_func} \textit{commandName} --- A procedure which will be done every time a file is selected (activated). The full path of the file name will be appended as an argument to this procedure.
\setcounter{enumi}{6}
\item{}
\textbf{-allow\_nonexistent} --- If the command used is \textbf{tk\_getOpenFile}, this will allow the user to enter a nonexistent file name. This name will be returned from \textbf{tk\_getOpenFile}, but it will still not exist. It is the programmer's responsibility to create this file afterwards.
\setcounter{enumi}{7}
\item{}
\textbf{-open\_button\_name} \textit{string} --- Alternate text to use for the ``Open'' or ``Save'' button. Not localized by Tk.
\end{enumerate}

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

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