Class ::tycho::File


Inherits: ::tycho::View - Source File - Contents: itk_options - destructor - public methods - public procs - protected method - protected variables - protected commons
This is a base class for widgets that have persistent data in files. It handles auto-saving, crash recovery saving, version control, saving before exiting, and other interfaces to the file system. A copy of the file is made automatically periodically with an interval given by the -autosaveinterval option. If the compiled version of Tycho is used (for example, running it with Ptolemy), then crash recovery files are also automatically created if the program crashes. Unfortunately, there appears to be no way to accomplish this when using a standard itkwish.

If the parent window is a Displayer object, then the menu bar of the Displayer object is populated with three menus. The "File" menu contains commands to open a file, insert a file, save data to a file, save as some other file name, print, evaluate the data, reload the last saved version, toggle read-only, version control, close the window, and exit the application. The "Window" menu contains commands to open new (blank) top-level windows of all types that have been registered with the File class using one of the register... procedures. It also contains commands to bring to the foreground any currently open editor that has a file name associated with it. Note that editors with the default name "NoName" do not appear on this list. Finally, a "Help" menu contains pointers to key Tycho documentation.

Here is an example:

::tycho::view File

Derived classes should normally redefine the methods

In order to support hypertext jumps into particular points in the display, the derived class may also redefine seeFragment, and currentPoint. These two should always be redefined as a pair, since currentPoint is assumed to return a syntax understood by seeFragment. Derived classes may wish to redefine indicateReadOnly, for example to disable menu entries. Finally, most derived classes will want to redefine focusin to give the focus to a key widget.

Itk_options

-autosaveinterval 5
Specify the interval (in minutes) between auto-save operations.
-data
Specifies initial data to display.
-file NoName
Set or change the name of the file being edited. Set the window title and icon name to match, and set the protected "file" variable equal to the file name. The filename is expanded into an absolute filename, resolving any references environment variables, user home directories, etc. See ::tycho::expandPath for details about how this is done. Note that the file is not actually loaded. Call reload after configuring this option to accomplish that (the constructor does this automatically).
-save 1
If zero, do not query for saving on exit.
-tmpfile 0
Specifies initial tmpfile to display.

Destructor

destructor
If the modified flag is set, query the user to see whether the file should be saved. If the user cancels the close, trigger an error. This has the effect of undoing the destruction.

Public constructs

Public Methods

altFile
Query the user for a filename, and edit its contents using the current editor.
autoSave
If the data has been modified, save the data to a file with the name given in the -file option, but with the prefix "#auto#". Then arrange to be called later again, with the time interval given by the option -autosaveinterval. A value of zero for this option disables auto-saving.
clear
In derived classes, clear the data being displayed or edited.
evaluate
Query the user for a filename, then evaluate its contents as Tcl commands.
filename
Return the name of the file associated with the object.
help
Open a window with help on the current widget. This should be redefined in derived classes.
hyperJump filename {point {}}
Open a file and go to its internal point identified by name. If the filename is the empty string, just call seeFragment, passing it the second argument. If the filename is relative (does not begin with "/", "~", or "$"), then prepend the directory of the file currently being edited or viewed. Then, expand the filename using ::tycho::expandPath and open the resulting file with ::tycho::File::openContext, which will choose an editor based on the filename extension. Finally, invoke seeFragment to view the specified point within the file. The format for the point argument depends on the type of file being opened. For HTML files, it will normally be the name of an anchor in the file. For text files, it will normally be either "{line linenumber}" or "{range start end}", where start and end have the form linenumber.characternumber.
indicateReadOnly bool
Indicate in the status bar and in the menus whether modifications are allowed on the buffer.
insertData data
Insert the specified data. In this base class, trigger an error.
insertFile
Insert the contents of a file. Open a file browser to query the user for a filename, and then insert the contents of that file via the method insertData.
isModified
Return 1 if the text has been modified since the last save, 0 otherwise.
markModified
If this view is with a Displayer object, show that the data has been modified by putting an icon in the lower left corner.
markUnmodified
If this view is with a Displayer object, show that the data is unmodified by clearing the icon in the lower left corner.
openWinMethod
Open a file browser, and then open an editor for the file. The editor is chosen based on the file extension, if the extension is recognized. Otherwise, the Edit class is used to open an ordinary text editor.
print
Print the contents of the file. The default behavior is an error.
reload
Reload from the last saved version of the current file. This method first disables read-only status (if it is set), then replaces the current data with data from the current file, and then sets read-only status based on the permissions of the file. The data is marked unmodified after loading the file, and the clipboard is restored to its form prior to the reload. If the file does not exist, then the current data is cleared, leaving a blank slate. If the current file exists but is not readable, an error occurs. The actual replacement of the data occurs via the method insertData.
revisionControl
Invoke revision control. If the file is under the control of a recognized revision control system (such as SCCS and RCS), then use that system. Otherwise, query the user about putting the file under revision control. A control panel is opened that permits the user to check in or check out the file, examine its revision history, etc.
save {name ""}
Save to a file, with an optional filename specified. If no filename is specified, then the name given in the -file option is used. If no -file option was given, the given name is "NoName", or the name begin with "#auto#" or "#crash#", then saveAs is invoked. Return 1 if it successfully saves, and 0 (or an error) otherwise.
saveAs
Invoke the file browser to prompt the user for a file name, and then, if the file is writable or creatable, save the contents of the editor to that file. Note that in the base class, this will eventually fail because we do not know how to save.
saveAsFile filename
Change the associated file to the specified file name and then save. Return 1 if the save is successful. Return 0 or trigger an error if the save is not successful.
saveCrash
Save data to a crash recovery file. The crash recovery filename is constructed from the true file name by prepending the prefix "#crash#".
saveQuery useSaveAs
If the file is marked as modified, then ask the user whether to save it. This method should be called before invoking any operation on the disk image of the file, such as checking it in, running a program on it, etc. If the optional argument is given and has a non-zero value, then saveAs is used instead of save, so that the user is prompted for a file name.

If the file is not modified, or if the -save option was given with value 0, return 2 and do nothing. If the file is modified and is saved, return 1. If the file is modified but not saved, return 0. If the user hits cancel, trigger a silentError, which unravels the calling stack all the way to the top-level. This has the effect of cancelling the entire operation.

toggleReadOnly
Toggle the read-only status of the file. If the file is under revision control (e.g. SCCS or RCS), then check in or check out the file.
windowMenuAddAll label
Add me to all "Window" menus of all current file objects. The argument, normally a file name, gives the menu label. If a menu entry already exists with the given label, leave it alone and ignore the call. Also ignore it if this View is not inside a Displayer.
windowMenuAppend obj label {type {}}
Place the name of an open file editor in the "Window" menu. The second argument, normally a filename, gives the menu label. If the given file object has a non-null value of its "viewType" variable, then the editor is placed into an appropriate sub-menu of the Window menu, otherwise it is appended to the end.
windowMenuRemoveAll filename
Remove the specified filename from the Window menu of all open File objects. The specified filename must match exactly the label given in the call to windowMenuAddAll that created the entry in the first place, and the object referenced by the menu must be this one.

Public Procs

callAutoSave obj
Check to see whether the object whose name is passed as an argument exists and is a File object, and if so, call its autoSave method.
emergencySave
Call the saveCrash method for all existing objects that are of class File, or are derived from class File.
makeTychoDir
If the directory ~/.Tycho does not exist, make it. If there is a file by the name "~/.tycho" (the old name for the Tycho initialization file), and no file named ~/.Tycho/tychorc.tcl, then copy ~/.tycho into ~/.Tycho/tychorc.tcl. NOTE: Unix implementation.
newEditor displayer viewer args
Open an editor with the specified displayer and viewer at the global scope and map it to the screen. Any arguments beyond the first two are passed to the viewer constructor. The name of the new window is returned.
openWin
Open a file browser, and then open an editor for the file. The editor is chosen based on the file extension, if the extension is recognized. Otherwise, the Edit class is used to open an ordinary text editor.
openContext filename
If an editor has been registered for the file or directory, use it to open the file or directory. Otherwise, if it is a file, open a plain text editor and return the name of the editor object. If a window already exists editing this file, simply raise it instead. New windows are always opened at the global scope. File names are expanded using ::tycho::expandPath, making them absolute and unique.
registerContents contents filecommand {description {}} {editorclass {}}
Register directory contents and an associated viewing command. By "directory contents" we mean a list of file or directory names that may exist inside a directory. The purpose of this method is to define an editor or viewer for relatively complicated data that is stored in multiple files inside a directory. When such an editor or viewer is registered by this method, then any future open-file command (via the openContext procedure in this class) will recognize a directory that contains the given contents and invoke the specified command. The directory must contain all of the specified contents items to be recognized.

The filecommand argument is a string with a "%s" embedded. The "%s" is replaced with the file name before invoking the command, using the Tcl formatcommand. For example, if the command is "::tycho::viewFile {%s} EditItcl", then the Tycho viewFile procedure will be used to open the file using an EditItcl view object. The braces around the "%s" allow the file name to have spaces.

If a description argument is a non-empty string, then the command will be added to the "Window" menu of all File objects opened in the future using the value of this description as the menu label. This permits the user to open a new blank editor of the given class.

If the editorclass argument is supplied and non-empty, then is selects the sub-menu of the Window menu into which the entry to open a blank editor will be placed. Legal values are "text", "graphics", and "tools".

registerExtensions extensions filecommand {description {}} {editorclass {}}
Register one or more file extensions and an associated viewing commands. Any future open-file command (via the openContext or displayData procedures in this class) will recognize a file name that has the given extension and will use the specified command to open it. Note that the leading period is considered part of the extension, as in ".itcl".

The filecommand argument is a string with a "%s" embedded. The "%s" is replaced with the file name before invoking the command, using the Tcl formatcommand. For example, if the command is "::tycho::viewFile {%s} EditItcl", then the Tycho viewFile procedure will be used to open the file using an EditItcl view object. The braces around the "%s" allow the file name to have spaces.

If a description argument is a non-empty string, then the command will be added to the "Window" menu of all File objects opened in the future using the value of this description as the menu label. This permits the user to open a new blank editor of the given class.

If the editorclass argument is supplied and non-empty, then is selects the sub-menu of the Window menu into which the entry to open a blank editor will be placed. Legal values are "text", "graphics", and "tools".

registerFilenames filename filecommand {description {}} {editorclass {}}
Register one or more file names and an associated viewing command. Any future open-file command (via the openContext procedure in this class) will recognize a file that has one of the given names and will use the specified command to open it.

The filecommand argument is a string with a "%s" embedded. The "%s" is replaced with the file name before invoking the command, using the Tcl formatcommand. For example, if the command is "::tycho::viewFile {%s} EditItcl", then the Tycho viewFile procedure will be used to open the file using an EditItcl view object. The braces around the "%s" allow the file name to have spaces.

If a description argument is a non-empty string, then the command will be added to the "Window" menu of all File objects opened in the future using the value of this description as the menu label. This permits the user to open a new blank editor of the given class.

If the editorclass argument is supplied and non-empty, then is selects the sub-menu of the Window menu into which the entry to open a blank editor will be placed. Legal values are "text", "graphics", and "tools".

registeredCommands name
Given a file or directory name, return the registered viewing commands. If none has been registered, return an empty string. Otherwise, the returned value the registered command for opening a file.
isFileOpen filename
Check if the file is already open, if YES, then return the window name, if NO, then return empty string.

Protected constructs

Protected Method

saveText
Return the text to save. In this base class, trigger an error, since we don't know how to save. This should be redefined in derived classes.

Protected Variables

file NoName
Set or change the name of the file being edited. Set the window title and icon name to match, and set the protected "file" variable equal to the file name. The filename is expanded into an absolute filename, resolving any references environment variables, user home directories, etc. See ::tycho::expandPath for details about how this is done. Note that the file is not actually loaded. Call reload after configuring this option to accomplish that (the constructor does this automatically).
modified 0
Indicate whether or not the file has been modified since it was last saved.
previousfile
Recall the previous filename associated with the window in case the name is changed.

Protected Commons

filesOpen
This array stores object names indexed by file names so that if the same file is opened a second time, we can just raise the window.
filesOpenTypes
This array stores the "type" of a file, indexed by file names, so that the Window submenus can be set up properly.
printCmd lpr
The most recently used print command (or the default if none). FIXME: default print command should be a preference.

Index of classes



Author: Edward A. Lee
Contributor: Joel King, Farhana Sheikh, Christopher Hylands
Version: @(#)File.itcl 1.154 12/15/96
Copyright: (c) 1995-1996 The Regents of the University of California.