| Header file: | savedialog.h |
| Object name: | fSAVEDIALOG |
| Object index: | 1 of 1 Object |
The fSAVEDIALOG is another one of those handy common dialogs - something which you see all over the place, and which is an integral part of any program. You should use this dialog when prompting to save - users seem to like familiarity.
If you'd like to save some hassel making those nasty filter strings, you might be interested in the MakeFilter() function. It's documented with the fOPENDIALOG component. If you include only savedialog.h, you will still have this function available.
| Prototype | Description |
| void SetRestoreDir(bool Set); | This function will allow you to specify whether or not the dialog should reset the directory it was looking at after the user has made their choice. Normally, when the user navigates around the system in the save dialog, this changes the current directory for your program. Passing TRUE for this will make the dialog reset that directory when it is done; passing FALSE will disable this. By default, this is FALSE. |
| void SetHideNetworkBtn(bool Set); | This function specifies whether or not to hide the network button that may be somewhere on the dialog. Passing TRUE for this will force the dialog to hide this button; passing FALSE will allow the dialog to show this button. By default, this is FALSE. |
| void SetValidation(bool Set); | This function sets whether or not the dialog should validate the filename before returning. By validation, I mean that it checks to see that the filename is valid and contains valid characters in it. If the filename does not contain valid characters, the user will be unable to dismiss the dialog normally. Passing TRUE makes the validation occur, or passing FALSE disables this validation. By default this is TRUE. |
| void SetFilter(char* Filter); | This function sets the filter list for the dialog box. Normally at the bottom of the dialog there is a combobox allowing you to select between several filetypes. With this function, you can set those filters. Now this string isn't your normal string - it has a specific syntax, which must be carefully done. If you fail to construct this string properly, then you will most likely crash the program with an access violation! Well, it's not that serious, provided that you terminate the string correctly. So why don't I get on with how to do it? Ok, a sample filter string would look like this: "Text Files (*.txt)\0*.TXT\0Text and Word Files (*.txt; *.doc)\0*.TXT;*.DOC\0All Files (*.*)\0*.*\0\0" Now in this string, you can see that the first string is the name of that filter, followed by a NULL character. After that is the filter. You can continue to add filters in this two-string combination to your hearts content. When you are finished, please terminate the string with a double-NULL. Failing to add the double NULL will crash your program! You do not need to add the filter in brackets on the end of the name of the filter, but generally this is a good practice, so the user knows exactly what filter is applied. Hint: you can use the MakeFilter() function to build the filter string. See the fOPENDIALOG documentation for details. |
| void SetFileName(char* Name); | This function sets the filename that will already be in the box that specifies the filename. Name is that name to be put in the box. |
| void SetFilterIndex(int Index); | This function sets the index of the filter that is selected by default. The first filter is 1, and the next is 2, and so forth through the list. Please do not try to enter 0 (Zero) - the results will be rather unexpected! |
| void SetDefaultExtention(char* Extention); | This function sets the default extention to be added to a filename if the user fails to type in an extention. If you don't set this, and the user does not type an extention, no extention will be added to the filename. The only condition is that Extention can not contain periods (.). |
| bool Execute(HWND Parent, char* Title); | This function actually shows the dialog and waits for the user to respond. If they clicked Save, then this function will return TRUE. If the user clicked Cancel, this function will return FALSE. Parent is the window that will act as the dialog's parent (but it can be NULL). Title is a short title at the top of the dialog. |
| char* GetFile(void); | This function returns the full filename of the file that was selected - the drive letter, path name, filename, and extention, all in one big package. |
| char* GetFileName(void); | This function returns the file that was selected - but only the filename and the extention portion of that filename. The pathname, drive letter, and all else are chopped off. |
| int GetFilterIndex(void); | This function returns the index of the filter that was selected, which could be useful in determining exactly how to save something. The number returns starts at 1 and progresses upward through the list. |
The following snippet gives a basic idea of how to use this component.
//Create an instance...
fSAVEDIALOG SaveDialog;
//Some general initialisation...
SaveDialog.SetFilter("Text File (*.txt)\0*.txt\0Word Document (*.doc)\0*.doc\0\0");
SaveDialog.SetFilterIndex(1);
SaveDialog.SetDefaultExtention("TXT"); //.TXT by default.
//Run the dialog...
if (SaveDialog.Execute(Window.GetHandle(), "Where do you want to save it?"))
{
//Ok, the user actually wants to save it. Where?
... = SaveDialog.GetFile();
} else {
//The user didn't want to save it. Oh well.
}
| Back to index | The FreeFoote Foundation Classes Documentation |