Overview

When working with computer applications it is wise to save your work often.

The Save file menu option saves the current user data in the application to the original file. But this is no use when you want to maintain a version of the file to compare against, which is a helpful if the edits after the save don't produce the required result.

The Save As... file option provides the ability to save the current user data to a new file, while leaving the original version of the file unaltered. After the file is saved the new file name (the intended draft or back-up file), becomes the working version in the application. And this is the problem of using the Save As... file menu feature to make back-up or draft files, because it is intended to make a copy of the file for use in its own right, not for making a file containing a draft or back-up copy of the user's data that can be reverted to, or compared against.

Problems with using Save As... to make draft or back-up copies of user data include,

inadvertently saving means that the back-up version of the file is lost as it is over-written by the current user data, which can be in a worse state than the now over-written draft or back-up version,
if the generated file is used in an application which references the file by file name, (for example a programming language source code file in an Integrated Development Environment, or a file included in a web page), then the original file will remain the referenced file, (unless the reference is updated), not the current version of the file.

To work-around the problems of the File > Save As... function as a back-up tool, the user must save their changes, then "save as..." their changes, then (optionally) close the current version of the data file, (save as... changes the current working file), then re-open the saved version of the file to make it the working version.

However, with my File > Save To... function, as the user edits the data in the application they can save the current data to a new draft or back-up file, e.g. myfile-bck1.ods, myfile rev 2.cpp, myfile r3.png etc. but then continue working on the file that was originally loaded.

The continuation of the Save To... file menu feature, is the Save To Draft file menu feature. When the user uses this feature, a file is created with either of the following automatically generated version identifiers appended to the root file name,

version identifier

example

current date and time

<root file name> 2009-dec-22-10-27.ext
<root file name> 2009-dec-22-11-15.ext
etc.

sequential number

<root file name> R1.ext
<root file name> R2.ext
etc.

The user can select the version identifier type and for the sequential number option, they can specify additional text to be included with the version number, e.g. Rn, Revn, bckn etc.

This page contains the following information on this "Tarsier Tool",
User Guide
Revision History
Software for Download
Source Code
Licensing
Technical Support

User Guide

Save To... file menu function

This example uses a simple text editor application to demonstrate the file save to functionality.

Using the File > New menu item to create a new file or the File > Open menu item to open an existing file.

After editing the File > Save menu item is used to save the user's data to a file, e.g. myfile.txt.

After further editing the File > Save As... menu item and dialog box are used to save the user's data to a new file, e.g. myfile-bck0.txt.

Use save as to save a draft of the changes after a lot of work.

If the data in the file is used in an another application, for example the file is a program source file or the file is used in a web page, the current version of the data, i.e. the example file myfile-bck0.txt, would not be used, but rather the original file, (in this case myfile.txt), would still be referenced by the application, until that application's configuration is edited, which is a time-wasting and error prone activity, especially if (wisely) frequent back-ups are made.

After major changes are made, if the data is saved using File > Save instead of File > Save As..., then the data in the back-up version is over-written. This results in a lot of wasted work if the changes don't work and the now over-written back-up version has to be restored!

An accidental use of save after major changes over-writes the back-up version.

Directory contents after accidental save. The data in the back-up version has been over-written.

However, using my File > Save To... menu item and dialog box the user's data to a new file, e.g. myfile-bck1.txt the user can save the current data in the application to a new draft or back-up file and the original data file remains in use. As the original data file remains in use in the application, a File > Save will save user data to it, not to the previously created draft or back-up file. Therefore there is no longer the danger of accidentally over-writing a draft or back-up file.

The save to function and dialog allow the user to save a named back-up of the application data.

but the original data file remains in use. (screen shot of app's window title bar.)

A final File > Save of the working version ensures that the original file contains the final version of the user's data, which ensures the user's latest data will be used by applications that are using the data contained in the file.

Directory contents after using save to and a final save. There are several back-up versions, but the original file is the most recent.

The directory contents after using several save tos to create draft or back-up files. A final save has saved the original file as the most recent.

Save To Draft file menu function

This example uses a simple text editor application to demonstrate the file save functionality.

Using the Edit > Preferences or Tools > Options dialog box, (as applicable to the operating system you're using), the user specifies whether the version identifier automatically appended to the root (original) file name is;

the current date and time,
a sequential number.

Selecting the automatic version number based on current date and time or based on a sequential number.

When using a sequential number, the user can specify the,

the numeral system, i.e.,

Arabic numerals, (0,1, 2 ...10, 11, etc.),
Roman numerals, large or small, (I, II,... or iii, iv, etc.),
Alphabetic, large or small, (A, B... or ...y, z, aa, ab, etc.),

any text the user wishes to add between the root (original) file name and the version sequence number, e.g. R, rev, bck etc. Spaces can be included if supported by the operating system.

After opening (File > Open menu item) an existing file or creating a new one, (File > New menu item),

this will be the original or root file name and will be used as the root of the file names automatically generated by the File > Save To Draft function.

As the user edits the data in the application they can save the current data to a new draft or back-up file with a single click of the File > Save To Draft function. The automatically generated addition to the root file name is generated based on the rules selected in the Preferences or Options dialog box, but the original data file remains in use. As the original data file remains in use in the application, a File > Save will save user data to it, not to the previously created draft or back-up file. Therefore there is no longer the danger of accidentally over-writing a draft or back-up file.

The save to draft function save a back-up of the application data to new file with an automatically generated addition to the original file name but the original data file remains in use. (screen shot of app's window title bar.)

Directory contents after using save to draft and a final save. There are several back-up versions, but the original file is the most recent.

The directory contents after using several save to drafts to create back-up files with a version identifier automatically added. A final save has saved the original file as the most recent.

I need to create menu icons for Save To... and Save To Draft, but have no artistic skill.

Revision History

Rev

Date

Details

1.0

10-May-2010

Initial version released

Software for Download

The code for this Tarsier Tool is an example to demonstrate the concept of the Save To... file menu function and the Save To Draft file menu function and associated Preferences or Options dialog box. It was used to generate the above application screen shots. This Tarsier Tool (code) is not a library, so you'll need to customise the code for your application, programming language or GUI API.

This Tarsier Tool is written in C++ and uses the wxWidgets API, (revision 2.8.10). I use wxWidgets because when I started writing GUI apps. its licence permitted applications developed using it to be used for commercial purposes without requiring a fee, whereas Qt required a license fee.

I find the wxWidgets API easy to use and so I hope you'll be able to copy the code and implement the Save To... and / or Save To Draft file menu functions easily in your application.

The example application was compiled and tested using gcc version 4.4.1 on Ubuntu 9.10.

To review or use this Tarsier Tool, use the following procedure.

Once the application files have been extracted use your favourite editor or IDE to view them and incorporate them into your application. Refer to the Source Code section for details of the key classes used to implement the Save To... file menu function and the Save To Draft file menu function and associated Preferences or Options dialog box.

If you want to run the example application, you will need to install and configure wxWidgets on your system if it is not already installed. You will then need to edit the make file to reference your wxWidgets build, (described in the above link).

Description

Shell Commands

Download tt10-001.tar.gz and save to a folder

Extract tt10-001.tar.gz.
Open a terminal window, navigate to the folder you saved tt10-001.tar.gz to and expand the file using the command

$ tar -xvzf tt10-001.tar.gz

This will create the directories tt10-001/src containing the source files and tt10-001/build containing the make file

Go to the build folder

$ cd tt10-001/build

Build the executable

$ make

Run the application with

$ ./tt10-001

Source Code

The demonstration code referenced in the previous section contains the source code for this Tarsier Tool.

Key item of the code is the FileNameManager class.
The class maintains a copy of the main (or root) file name in use, which must be updated during file open, file new and file save as events. For the save to event, the class is used to store the the main (or root) file name, while the normal save as dialog box and actions are used to save the current data to the user specified file.

For the save to draft events, the class uses the main (or root) file name to obtain the draft file name. For the current date and time option, this will be the main (or root) file name with the current time and date appended. For the sequential number option, the directory containing the file will be searched for previous draft files and the class will provide the main (or root) file name with the new highest revision number appended.

The class functions are as follows.

fileOpened(...)

set the main (or root) file name stored in the instance. Use after opening a new file, or performing a save as.

getDraftFullPathNumeric(...)

returns the draft file name to save the current data to using a numeric revision identifier, based on the specified number system and any revision identifying text. The number system is specified using a string, containing the text "arabic", "roman" or "alphabetic".

getDraftFullPathTimeDate()

returns the draft file name to save the current data to using a using the current time and date as the revision identifier.

getFullName()

returns the full file name (e.g. myfile.txt) of the main (or root) file.

getFullPath()

returns the full path name (e.g. directory path/myfile.txt) of the main (or root) file.

newFile()

use to clear the main (or root) file name stored in the instance after a new file is created.

The OptionDialog class creates an options dialog box with a single tab to provide the options for the save to draft function. You will need to add the options tab on this tab to your application's option or preferences dialog.

The user options set in the OptionDialog class are communicated to the FileNameManager class in my application in the UserOptions class, which stores the specified user option names and values in an STL Map.

The FileNameManager class does not use the UserOptions class directly, making it easier for you to change the communication method. However, note that there is a run-time linking between the OptionDialog class and the FileNameManager class in the names used to store the options. While simplifying the class structure, this removes compile time checking of the link, e.g. the application uses the text num-sys-sel to communicate number system selected by the user in the OptionsDialog to the FileNameManager class. If you change the text in the OptionDialog class, but not where the value is looked up and passed to the FileNameManager class, then the application will still compile, but will not work.

The C++ classes in the application are as follows.

tt10001.cpp

the main application class and is executed from the command line. Calls the wxWidget application setup functions and creates the main application as well as setting the application's event handler linking.

ApplicationLogic.cpp

contains the application's logic, in this case, merely handling file action events and loading and saving the current text window from and to a file.

GUIBuilder.cpp

called from the ApplicationLogic class to build the GUI components of the application, i.e. menu bars.

FileNameManager.cpp

called from the ApplicationLogic class to generate the file name for a draft copy of the application's current data file, based on current date and time, or the next number in sequence based on existing draft files in the current data file's directory.

NumberSystemConverter.cpp

called from the FileNameManager class to convert numbers between Arabic, Roman and alphabetic number systems. This class can be used independently of this demonstration "Tarsier Tool".

OptionsDialog.cpp

this class creates an options (or preferences) dialog box with a single tab to provide the options for the save to draft function.

UserOptions.cpp

this class is used to communicate data (the user's options in this case) between classes in the application. The data is stored based on a string key and can handle Boolean, integer and string values, using STL Maps. The class handles updating an existing key's value. This class can be used independently of this demonstration "Tarsier Tool".

License Fee

This "Tariser Tool" is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. There is no license fee for personal use of this tool. However, if you are using this software within software that you are developing and intend to sell, please e-mail me for details of the license fee.

Please note that this Tarsier tool is distributed with

NO WARRANTY

Section 5 Disclaimer of Warranties and Limitation of Liability.

Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.
To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.
The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability.

Technical Support

Frequently Asked Questions

There are no FAQ for this "Tarsier Tool".

If you have a question, please e-mail it to me. Please ensure that you identify that the question is about my Save To... File Menu Function (TT10-001) "Tarsier Tool".

Bug Reports

If you suspect a bug in this "Tarsier Tool" please e-mail me a description.

Please ensure you identify that the bug report is about my Save To... File Menu Function (TT10-001) "Tarsier Tool", the compiler and the operating system in the e-mail and include as much detail as possible; including a simple example application is always helpful! But make sure it does not contain proprietary or confidential information.

Back to Available Tarsier Tools