https://github.com/softcircuits/datafilemanager
WinForms component that helps manage an application's data files.
https://github.com/softcircuits/datafilemanager
Last synced: about 1 year ago
JSON representation
WinForms component that helps manage an application's data files.
- Host: GitHub
- URL: https://github.com/softcircuits/datafilemanager
- Owner: SoftCircuits
- License: mit
- Created: 2020-05-19T14:06:24.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2025-01-19T18:53:15.000Z (over 1 year ago)
- Last Synced: 2025-03-30T05:11:27.510Z (about 1 year ago)
- Language: C#
- Size: 59.6 KB
- Stars: 3
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: License.txt
Awesome Lists containing this project
README
# DataFileManager
[](https://www.nuget.org/packages/SoftCircuits.DataFileManager/)
## Introduction
DataFileManager is a WinForms component that helps manage an application's data files.
This component assists with tracking whether or not the current file has been saved, what the current file's name is, whether or not changes have been made, and helps ensure the user doesn't exit or load a file without having a chance to save the current file.
## Using the Library
Start by adding the component to your form.
#### Implementing File Commands
To implement the file commands, direct your file menu commands to the component.
```cs
private void newToolStripMenuItem_Click(object sender, EventArgs e)
{
dataFileManager1.New();
}
private void openToolStripMenuItem_Click(object sender, EventArgs e)
{
dataFileManager1.Open();
}
private void saveToolStripMenuItem_Click(object sender, EventArgs e)
{
dataFileManager1.Save();
}
private void saveAsToolStripMenuItem_Click(object sender, EventArgs e)
{
dataFileManager1.SaveAs();
}
```
#### Implement Application-Specific File Handling
Next, you need to add event handlers to perform your application-specific file reading and writing. The `DataFileEventArgs` class includes the `FileName` property, which is the full file name of the current file or `null` if the file has no name.
Note that you don't need to worry about File Open or File Save dialogs, and you also don't need to implement exception handling. These are all done for you by the library.
```cs
private void dataFileManager1_NewFile(object sender, DataFileEventArgs e)
{
textBox1.Text = string.Empty;
}
private void dataFileManager1_OpenFile(object sender, DataFileEventArgs e)
{
textBox1.Text = File.ReadAllText(e.FileName);
}
private void dataFileManager1_SaveFile(object sender, DataFileEventArgs e)
{
File.WriteAllText(e.FileName, textBox1.Text);
}
```
#### Tracking Modifications
An important element in ensuring the user always gets a chance to save any changes made is to ensure the current file is marked as modified whenever a change is made. In our example, all the data is in a `TextBox` control, and so we add a handler for the `TextChanged` event. You would need to ensure you set the `IsModified` flag in response to any changes made.
```cs
private void textBox1_TextChanged(object sender, EventArgs e)
{
dataFileManager1.IsModified = true;
}
```
Now when you call the `New()` or `Open()` methods, the library will automatically prompt to save the current document if it has been modified. If the user cancels that prompt, or if there is an error saving the file, the `New()` and `Open()` methods will abort to avoid losing changes to the current document.
One case you also need to handle is when the user closes your form. In this case, you can call the `PromptSaveIfModified()` method directly. This method returns `true` if the current file has not been modified, if the user chose not to save the changes, or if the changes were successfully saved. Otherwise, this method returns false. In the example below, the code cancels the form closing if `PromptSaveIfModified()` returns false.
```cs
private void Form1_FormClosing(object sender, FormClosingEventArgs e)
{
if (!dataFileManager1.PromptSaveIfModified())
e.Cancel = true;
}
```
#### Displaying the Current File
Most applications set the title bar text to something like *Current Document - AppName*. The DataFileManager library makes it easy to ensure your title bar is always current by providing the `FileChanged` event.
The `DataFileEventArgs` class also includes the `FileTitle` property, which returns just the file name portion of `FileName` or `"Unititled"` if the file has no name.
```cs
private void dataFileManager1_FileChanged(object sender, DataFileEventArgs e)
{
Text = $"{e.FileTitle} - Test App";
}
```
#### Customizing the File Open and File Save Dialog Boxes
Finally, there are a couple of component properties you can set in the designer. The `DefaultExt` and `Filter` properties correspond to the `DefaultExt` and `Filter` properties of the `OpenFileDialog` and `SaveFileDialog` components. These properties determine the default file extension added when saving a file and no extension was specified, and control the choices that appear in the *Files of type* or *Save as file type* box in the dialog box.